[ThomasK33]

What you get

Each queued @mention now has a deadline: connection_timeout + connection_wait_delay ms after you sent it (10.6 s by default). No handshake and no disconnect moves the deadline. At its deadline, a mention that is still queued leaves with an error, unless a ready Claude is connected. A ready Claude is one that completed its WebSocket handshake connection_wait_delay ms ago (600 ms by default).

While a ready Claude is connected, no deadline clears a mention. The queue drains to it, oldest first, 25 ms apart, also past the deadlines. When that Claude leaves, the next flush clears every mention whose deadline passed meanwhile, with an error, and the rest wait for their own deadlines.

So a Claude that completes its handshake less than connection_timeout ms after a send, and stays connected, gets that mention, and every other mention still queued when it is ready. With 100 mentions sent at once and a handshake 8 s or 9.8 s later, all 100 arrive.

The error says which case you are in:

• No client connected: "Connection timeout - clearing N queued @ mentions" (the same text as before).
• A client connected that is not ready yet: "Send timeout - clearing N queued @ mentions that the connected Claude did not take in time".

Before this change, each handshake stopped the connection timeout. Clients that connected and left without overlapping (for example a new client every 1000 ms that stays 300 ms) held a mention for as long as they kept doing it, with no error. They still never become ready, so the mention leaves with an error at its deadline.

Another client's handshakes no longer delay a queued mention. A mention goes out once some connected client is ready. The broadcast then reaches every connected client, including one that connected later and is still in its own wait. Before, while one Claude stayed connected, each handshake of another client restarted the wait of a flush that was already due.

When libuv refuses a write at once, you now see an error too. luv returns nil and the error for such a write and never runs its callback. send_message ignored that return, so broadcast never reported, and the queue dropped the mention without a word.

Behavior changes

1. A drop no longer gives a queued mention a fresh connection_timeout. The deadline counts from the send.
2. Mentions sent at different times time out at different times. Before, one timeout from the first queued mention cleared them all.

These fix the Codex round-6 finding on #454 (thread), which the user waived for #454 so that it ships here. They also fix a gap the advisor on #454 found, the Codex round-1 finding on this PR, and the verifier's findings on 0585211, d1a6724 and cefe258.

Change

• init.lua queue_mention: it stamps each mention with its deadline, and starts M.state.connection_timer when it is not running.
• init.lua expire_mentions, the connection_timer callback: while no ready client is connected, it clears the queued mentions whose deadline passed, with one error, and starts the timer again for the oldest mention left. When the oldest mention went out since, it clears nothing. While a ready client is connected, it clears nothing, makes sure a flush is due, and stops.
• init.lua flush_mention_queue: it sends the oldest mention only once some connected client is ready (ms_until_a_client_is_ready). Otherwise it waits for the first such moment and checks again then. A flush that finds no ready client calls expire_mentions, so the mentions whose deadline passed while a ready client took the queue leave at once.
• init.lua schedule_mention_flush: it no longer starts or stops the timeout while the queue holds a mention. The bound on the wait for a ready client (ready_wait_since) is gone, as the deadline covers it.
• init.lua M.process_mention_queue(true), the handshake hook: it no longer restarts the flush timer.
• server/client.lua: a client records connected_at when its handshake completes, and get_client_info returns it.
• server/client.lua send_message: it passes the error of a write that libuv refuses at once to the callback. broadcast then counts that write as failed and still calls on_written once. Main added a write helper that every socket write goes through (fix(server): drop a client that answers pings but never reads #467). It now returns what tcp_handle:write returned, and it stops a large frame at the first piece that libuv refuses at once (Codex round 4, hardening: libuv refuses all pieces or none, and at_mentioned frames are never split).
• config.lua and dev-config.lua: the connection_timeout comment says what the setting does now.
• types.lua, the comments in init.lua and server/client.lua, and lua/claudecode/README.md state the rules above.
• fixtures/issue-70/README.md names the deadline and expire_mentions in place of the removed start_connection_timeout_if_needed.

Tests

All tests are in tests/unit/mention_queue_spec.lua unless noted. The tests run the real server code on a fake libuv loop, so each time below is exact.

Tests that fail on cefe258, the previous head:

• F1: 100 mentions sent at once all reach a Claude whose handshake comes 8000 ms later, and the same at 9800 ms.
• F1: when a ready Claude leaves after the deadline, the rest leave at the next flush: one error, within 25 ms of the drop, for every mention it did not get.
• F1: when a ready Claude leaves after the deadline while another waits, the rest leave at once: the same, while a second Claude that is not ready yet is connected.
• D: a Claude that gets ready just at the deadline gets the mention.
• F1: a ready Claude that leaves before its handshake callback ran does not strand the queue. The verify-mention-queue model found this path once I gave it the drain rule: Neovim runs the handshake's on_open callback late when its loop was busy, so the deadline can find Claude ready before any flush is due. Without the flush that the spared deadline now schedules, a Claude that left before on_open ran left the queue with nothing that sent or cleared it.
• In tests/unit/server/connection_lifecycle_spec.lua: stops at a piece that libuv refuses at once, and passes its error to the callback once.

On real Neovim 0.12.3, with the plugin's own timers and a loopback WebSocket client: 100 mentions sent at once, and a handshake 8.6 s later. On this head all 100 arrive, in order, with no error. On cefe258, 36 arrive, and at 10.6 s you see "Send timeout - clearing 64 queued @ mentions that the connected Claude did not take in time".

Tests that fail on d1a6724:

• S: clients that connect every <period> ms and stay <life> ms do not hold a mention past its deadline, for 1000/300, 700/300, 650/500 and 900/100 ms: no two clients connected at once. The mention is sent 1 ms after the first handshake. Each test expects one error at 10601 ms, and no client receives the mention.
• S: clients that overlap but each leave before they are ready do not hold a mention past its deadline: a new client every 200 ms that stays 300 ms. One error at 10601 ms, with the Send timeout text.
• A, F4: a Claude whose handshake comes 10.3 s after the send is not ready by the deadline: you see an error
• H: a handshake and a drop just before the deadline do not move it
• B: mentions sent 5 s apart with no Claude each time out at their own deadline: errors at 10.6, 15.6 and 20.6 s.
• B: of two mentions sent 5 s apart, a Claude ready between their deadlines gets the second
• B, C: :ClaudeCodeStop drops the deadline of the old mention: a mention sent after a restart gets its own
• C: a stop cancels a deadline whose callback already waits for the main loop
• F1: when a ready Claude leaves in the middle of the queue, the rest leave at their deadline: one error at 10.6 s for every mention it did not get. It passes on cefe258.

Tests that pass on d1a6724 and pin a rule:

• A: a Claude whose handshake comes 9.9 s after the send is ready at 10.5 s and gets the mention
• B, control: the deadline of a mention that went out clears no later mention
• E: a send while a flush is due does not postpone that flush. It kills the queue_mention mutant that the verifier found surviving (F2-send-restarts-flush below).

Tests from earlier rounds:

• D: handshakes of other clients do not postpone a flush that is due for a connected Claude. It fails on 3f42e01, the last fix(mention): deliver queued @mentions once, in order, or report an error #454 head.
• D: when the Claude a flush was kept for leaves, a newly connected Claude still gets connection_wait_delay. It fails on 7e8860c, the first head of this PR.
• The readiness rule: D: a Claude whose handshake came 700 ms after its TCP connect still gets connection_wait_delay, D: a Claude whose CLOSE frame arrives as a flush is due does not count as ready, D: when the Claude a flush waits for leaves during the wait, the next Claude gets its own wait, and D: a Claude that answered a ping just now has still been connected since its handshake.
• H: a write that libuv refuses at once shows an error too, and a server_spec.lua case where one client's write is refused and another's succeeds: on_written runs once, with 1.

The fake loop fails a test when its timers keep firing at one moment, so a mutant that loops makes a test fail instead of hanging the run.

Three earlier tests contradicted the final rules, and I replaced them: "H: after a drop in the wait, the mention gets a whole connection_timeout for Claude to come back", "B, control: the connection timeout runs from the first queued mention, not from the latest", and, on cefe258, "D: a Claude that gets ready just at the deadline is too late". I removed "C: a flush that the deadline cancelled does not send a mention sent right after the deadline": its path no longer exists, as no deadline clears a mention while a ready Claude is connected.

Mutants: I ran 47 mutants of the queue, deadline, drain, readiness, broadcast and write-report code. Each mutant changes one guard alone. 46 of them make at least one test fail.

no-identity-check survives. start_timer runs a callback only while its timer is still the one in M.state, and the mutant drops that check, so a stale flush or deadline callback runs once more. Every queue callback re-checks the queue and the clients, and no deadline clears a mention while a ready client is connected. So a stale callback can no longer send a mention early or clear one, and I found no path that tells the two apart. I kept the check: without it, a stale callback stops the live timer of its name.

C2-connected-at-accept now sets connected_at from client.last_pong, which after #488 holds the time of the TCP accept (or of the last pong). Before, it left connected_at nil and duplicated connected-at-unset.

The definitions follow, as the code each mutant replaces (-) and its replacement (+). A mutant with no + lines deletes the code.

The 47 mutants

1. closing-counts in init.lua

   - takes no frames.
   -       if info.state == "connected" and info.handshake_complete == true then
   + takes no frames.
   +       if (info.state == "connected" or info.handshake_complete == true) and info.handshake_complete == true then

2. no-identity-check in init.lua

   - if M.state[name] == timer then
   + if true then

3. flush-ignores-broadcast-result in init.lua

   - if not server.broadcast("at_mentioned", params, report_unwritten("queue", mention.file_path)) then
   + if not (server.broadcast("at_mentioned", params, report_unwritten("queue", mention.file_path)) or true) then

4. stop-keeps-queue in init.lua

   -   -- Clear the queued @ mentions and stop the queue's timers: nothing queued before the stop reaches Claude
   -   clear_mention_queue()

5. queued-path-raw in init.lua

   -     queue_mention(mention.file_path, mention.start_line, mention.end_line)
   +     queue_mention(file_path, start_line, end_line)

6. immediate-overtakes in init.lua

   - if immediate and #mention_queue() == 0 then
   + if immediate then

7. no-on-open in server/client.lua

   -         if on_open then
   -           on_open(client)
   -         end

8. broadcast-always-true in server/init.lua

   - return tcp_server.broadcast(M.state.server, json_message, on_written) > 0
   + tcp_server.broadcast(M.state.server, json_message, on_written)
   +   return true

9. tcp-broadcast-counts-closing in server/tcp.lua

   -     if client.state == "connected" then
   -       sent = sent + 1
   +     if true then
   +       sent = sent + 1

10. bad-path-queued-anyway in init.lua

-     if not mention then
-       return false, format_error
-     end
-     queue_mention(mention.file_path, mention.start_line, mention.end_line)
+     mention = mention or { file_path = file_path, start_line = start_line, end_line = end_line }
+     queue_mention(mention.file_path, mention.start_line, mention.end_line)

11. tcp-broadcast-ignores-on-written in server/tcp.lua

-       if on_written then
-         pending = pending + 1
+       if false then
+         pending = pending + 1

12. tcp-broadcast-reports-before-writes in server/tcp.lua

-     if dispatched and not reported and pending == 0 and sent > 0 then
+     if dispatched and not reported and sent > 0 then

13. tcp-broadcast-counts-failed-writes in server/tcp.lua

-           if not err then
-             written = written + 1
-           end
+           written = written + 1

14. unwritten-silent in init.lua

-       logger.error(component, "Claude's connection failed
+       logger.debug(component, "Claude's connection failed

15. mock-broadcast-no-report in server/mock.lua

-   if written > 0 and on_written then
+   if false then

16. immediate-on-written-noop in init.lua

- M.state.server.broadcast("at_mentioned", params, report_unwritten("command", formatted_path))
+ M.state.server.broadcast("at_mentioned", params, function() end)

17. immediate-reports-raw-path in init.lua

- report_unwritten("command", formatted_path)
+ report_unwritten("command", file_path)

18. tcp-broadcast-no-dispatched-guard in server/tcp.lua

-     if dispatched and not reported and pending == 0 and sent > 0 then
+     if not reported and pending == 0 and sent > 0 then

19. send-message-ignores-refusal in server/client.lua

-   if not queued and err and callback then
+   if false then

20. flush-ignores-readiness in init.lua

-   if wait and wait > 0 then
+   if false then

21. readiness-uses-newest-client in init.lua

-       wait = wait and math.min(wait, left) or left
+       wait = wait and math.max(wait, left) or left

22. handshake-restarts-flush in init.lua

-     schedule_mention_flush(M.state.config.connection_wait_delay)
-   else
+     stop_timer("mention_timer")
+     schedule_mention_flush(M.state.config.connection_wait_delay)
+   else

23. connected-at-unset in server/client.lua

-         client.connected_at = vim.loop.now()

24. C2-connected-at-accept in server/client.lua

-         client.connected_at = vim.loop.now()
+         client.connected_at = client.last_pong

25. I4-closing-counts-ready in init.lua

-     if info.state == "connected" and info.handshake_complete == true and info.connected_at then
+     if info.handshake_complete == true and info.connected_at then

26. I9-readiness-from-last-pong in init.lua

-       local left = math.max(0, info.connected_at + M.state.config.connection_wait_delay - vim.loop.now())
+       local left = math.max(0, info.last_pong + M.state.config.connection_wait_delay - vim.loop.now())

27. I12-no-recheck-after-wait in init.lua

-   local wait = ms_until_a_client_is_ready()
-   if wait and wait > 0 then
+   local wait = not M.state.skip_ready_check and ms_until_a_client_is_ready()
+   M.state.skip_ready_check = nil
+   if wait and wait > 0 then
+     M.state.skip_ready_check = true

28. no-remove-head in init.lua

-   table.remove(queue, 1)
-   logger.debug("queue", "Sent queued
+   logger.debug("queue", "Sent queued

29. send-restarts-flush-v2 in init.lua

-   elseif M.is_claude_connected() and not M.state.mention_timer then
+   elseif M.is_claude_connected() then

30. F2-send-restarts-flush in init.lua

-     start_timer("connection_timer", timeout, expire_mentions)
-   end
-   schedule_mention_flush(debounce_delay)
+     start_timer("connection_timer", timeout, expire_mentions)
+   end
+   stop_timer("mention_timer")
+   schedule_mention_flush(debounce_delay)

31. clear-keeps-deadline in init.lua

-   M.state.mention_queue = {}
-   stop_timer("mention_timer")
-   stop_timer("connection_timer")
+   M.state.mention_queue = {}
+   stop_timer("mention_timer")

32. empty-queue-keeps-deadline in init.lua

-   if #mention_queue() == 0 then
-     stop_timer("mention_timer")
-     stop_timer("connection_timer")
+   if #mention_queue() == 0 then
+     stop_timer("mention_timer")

33. timeout-silent in init.lua

-       logger.error("queue", "Connection timeout - clearing "
+       logger.debug("queue", "Connection timeout - clearing "

34. send-timeout-silent in init.lua

-       logger.error(
-         "queue",
-         "Send timeout
+       logger.debug(
+         "queue",
+         "Send timeout

35. F4-connection-text-while-connected in init.lua

-     if M.is_claude_connected() then
-       logger.error(
+     if false then
+       logger.error(

36. deadline-restarts-on-send in init.lua

-   if not M.state.connection_timer then
-     start_timer("connection_timer", timeout, expire_mentions)
-   end
+   start_timer("connection_timer", timeout, expire_mentions)

37. deadline-without-wait-delay in init.lua

-   local timeout = M.state.config.connection_timeout + M.state.config.connection_wait_delay
+   local timeout = M.state.config.connection_timeout

38. handshake-stops-deadline in init.lua

-   if from_new_connection then
-     schedule_mention_flush
+   if from_new_connection then
+     stop_timer("connection_timer")
+     schedule_mention_flush

39. handshake-moves-deadline in init.lua

-   if from_new_connection then
-     schedule_mention_flush
+   if from_new_connection then
+     local timeout = M.state.config.connection_timeout + M.state.config.connection_wait_delay
+     for _, queued in ipairs(mention_queue()) do
+       queued.deadline = vim.loop.now() + timeout
+     end
+     if #mention_queue() > 0 then
+       start_timer("connection_timer", timeout, expire_mentions)
+     end
+     schedule_mention_flush

40. expire-clears-whole-queue in init.lua

-   while expired < #queue and queue[expired + 1].deadline <= now do
+   while expired < #queue do

41. expire-keeps-mentions in init.lua

-     for _ = 1, expired do
-       table.remove(queue, 1)
-     end

42. expire-no-rearm in init.lua

-   else
-     start_timer("connection_timer", queue[1].deadline - now, expire_mentions)
-   end
+   end

43. expire-rearms-for-newest in init.lua

- start_timer("connection_timer", queue[1].deadline - now, expire_mentions)
+ start_timer("connection_timer", queue[#queue].deadline - now, expire_mentions)

44. F1-expire-while-ready in init.lua

-   if ms_until_a_client_is_ready() == 0 then
+   if false then

45. F1-wait-keeps-overdue in init.lua

-     expire_mentions()
-     if #mention_queue() > 0 then
+     if #mention_queue() > 0 then

46. F1-no-client-keeps-overdue in init.lua

-     logger.debug("queue", "No connected client took queued @ mention: " .. mention.file_path)
-     expire_mentions()
- 
+     logger.debug("queue", "No connected client took queued @ mention: " .. mention.file_path)
+ 

47. F1-spare-without-flush in init.lua

-     schedule_mention_flush(inter_message_delay)
-     return
-   end
-   local queue = mention_queue()
+     return
+   end
+   local queue = mention_queue()

Validation

All on the pushed head, after merging main at 09b78fd. #488 on main removed client.last_pong = vim.loop.now() from the 101 write callback, so the merge sets client.connected_at = vim.loop.now() there, the handshake time as before. Outside covered.lock and that line, the change of this PR is the same as at 3de15f5, apart from index lines and hunk offsets:

• luacheck on lua/ and tests/: 0 warnings / 0 errors in 173 files
• busted, full suite, shuffled: 1516 successes / 0 failures / 0 errors / 20 pending, with --coverage (seed 1794411584) and without (seed 12345)
• Real-Neovim integration tests (Neovim 0.12.3): 313 success, 0 failed
• treefmt --ci: 0 files changed
• The 47 mutants: 46 killed, 1 survived (no-identity-check, see above)
• Real Neovim 0.12.3, 100 mentions at once and a handshake 8.6 s later: 100 received, in order, 0 errors
• verify-diff-lifecycle: I re-recorded covered.lock after each change to a covered file, and check.sh passes.
• verify-mention-queue (the model for the skill PR that follows this one, not in this PR): every TLC check passes on this code, with the drain rule and its three new guards. check.sh still exits 3 (STALE) on this head, because the skill's covered.lock needs a re-record. The skill PR does that.

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: xhigh

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-11T12:30:57.760376Z	d514686	Manual request
🔒 Security Review	✅ Completed 2026-11-11T12:31:23.432775Z	d514686	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: 3de15f5ca4

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: 3de15f5ca4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: d514686211

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: d514686211

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[ThomasK33]

Waiver recorded for this run: a lock-only merge of main (the PR's own diff outside .agents/skills/verify-diff-lifecycle/covered.lock byte-identical, check.sh passing, CI green on the new head) may be pushed past the six-round cap and merged on the last clean Codex verdict. This PR is at round 6 with Codex clean on d514686; its next push is such a merge.

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

[ThomasK33]

Waiver recorded for this PR: the maintainer allowed the merge of main that changes one line of this PR's own diff (client.connected_at = vim.loop.now() in server/client.lua, needed after #488 removed the last_pong reset from the handshake callback) to be pushed past the round cap and merged on CI green plus the last clean Codex verdict (d514686), without a new Codex round.

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high