fleet/fleetd
3
0
Fork 0
Code Issues 73 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

A lead cannot ack its own held peer mail, so every lead-to-lead message it polls is delivered a second time and costs a whole lead turn #563

New Issue
Open
opened 2026-09-12 11:29:57 +02:00 by ltms · 1 comment
ltms commented 2026-09-12 11:29:57 +02:00
Owner
Copy Link
Copy Source

Filed by the mac lead from its own use, 2026-09-12, on main at 4f9aba4. This is an ergonomic defect in the bridge's own lead-to-lead channel, and it is expensive in the one resource the lead layer is metered on: lead turns.

The shape

Peer mail has two delivery routes and only one of them consumes the message.

route reads the body acks costs
fleet_poll{coordId: <self>} yes, in full no one tool call
the pane push loop yes, in full yes a whole lead turn

The documented way to read your own held mail is fleet_poll{coordId} — the intent→tool table in CLAUDE.md says it is "the only way to read the full body", because fleet_list's held[] gives a truncated preview. That call deliberately does not ack.

There is then no way to say "I have read this, stop pushing it." The pane push fires later regardless, and the lead spends a full turn re-reading a message it has already read and already answered.

Measured, this turn

fleet_ack refuses both plausible targets, with the same message:

$ fleet_ack{target: "mac",      msgId: "708b8b31-…"}
708b8b31-… is not in mac's reply inbox (wrong id, wrong target, or already acked).
Held lead-to-lead (peer) mail cannot be acked this way — read it with fleet_poll{coordId}.

$ fleet_ack{target: "fleet01",  msgId: "708b8b31-…"}
708b8b31-… is not in fleet01's reply inbox (wrong id, wrong target, or already acked).
Held lead-to-lead (peer) mail cannot be acked this way — read it with fleet_poll{coordId}.

The refusal is deliberate and correctly worded — it is not a bug in fleet_ack. It is the absence of any tool that does the job.

That the pane push is the acking route is measured too, not inferred. Two messages were in held[], were pushed to the lead's pane, and were gone from held[] on the next fleet_list, with no fleet_ack call in between: b111d25a and 057b586c.

Current queue cost: fleet_list reports heldCount: 4. All four have already been read in full by this lead via fleet_poll{coordId}, and all four have been answered. Each will still be pushed. That is four lead turns already owed to messages that are fully handled.

057b586c is the clearest case: the sender themselves retracted it in a later message ("§1 ACCEPTED IN FULL — my premise was wrong… I have struck the proposal"), the lead had already answered it, and it still consumed a turn.

Why this is not just a nuisance

  1. It burns the scarcest resource. A lead turn is a full context read. Members are cheap and parallel; the lead is one metered session. Spending its turns re-reading answered mail is the most expensive possible way to waste this layer.
  2. It teaches the wrong behaviour. The rational response is stop calling fleet_poll{coordId} — take the truncated held[] preview and wait for the push. That is exactly backwards: it makes a lead act on a preview, or delay acting on a time-critical message until the push happens to land. One of the messages in this session was marked TIME-CRITICAL IF #553'S REWORK IS STILL IN THE FILE. Waiting for a push was not an option; polling cost a duplicate turn.
  3. It is the week's recurring shape, in our own tool surface. The same fact arrives on two channels with no marker saying which one you are reading, and nothing reconciles them. That is #512's two-states-one-symbol and #551's two-records-one-event, at the transport layer.

What is wanted

Give the reader a way to consume. The minimal change is an ack route for peer mail — either

  • fleet_ack{coordId, msgId}, symmetric with the member-inbox form, or
  • an opt-in flag on the existing read, e.g. fleet_poll{coordId, ack: true}.

Do not "fix" this by having the push loop suppress anything fleet_poll has seen. That silently converts a peek into a consume, and then a lead that polls and dies mid-turn loses the message with no record that it ever arrived. The reader must say so explicitly. Peek and consume are two operations and they must stay two.

Whoever takes this should decide and write down in the PR:

  • whether a default ack on fleet_poll{coordId} would be better than opt-in. It would match the member-inbox ergonomics, but it makes the documented "read the full body" call destructive, and GET /sessions/{id}/replies draining on first read has already cost this project a report. Argue it either way; do not leave it undecided.
  • what happens to a message acked while its push is already in flight. That race must not double-deliver or drop.

Acceptance

  • A test that a peer message acked through the new route is not subsequently pushed to the lead's pane. Red before the change.
  • A test that a peer message read with fleet_poll{coordId} and not acked is still pushed — the peek semantics must survive, and this is the test that catches a fix that over-reaches into silent consumption.
  • A test that acking a msgId that is not in the caller's own held mail is refused, and that a lead cannot ack another lead's mail. Identity comes from the connection; this must not become a route to consume a peer's inbox.
  • The intent→tool table in CLAUDE.md and the byte-identical wiki copy are updated in the same change — the table currently tells every lead that fleet_poll{coordId} "never acks", which this change makes conditional or false. The canonical-block sync check must print in sync: True; the lead runs that check, not the worker (a member's worktree has wiki/ uninitialized).
  • An entry in wiki/11-Features.md: what it does · the knob · why it exists · the gotcha.
  • Each new test proven by a mutation: line-anchored sed only, the pristine full line counted by exact string equality (awk '$0==p', never a regex — a regex can match inside a comment the mutation inserted, which produced a false "not applied" on #544). The count must drop by exactly one and the report must state which two numbers — 2 → 1 is a valid proof when identical text appears elsewhere; 1 → 0 is only the common case. Restore byte-identical under a full shasum -a 256, then a green control.
  • Report the exit code next to any test count. A dead suite reports zero failures.

Out of scope

  • The member reply inbox (fleet_poll{target} → fleet_ack{target, msgId}). It already works; do not change its semantics to match.
  • The pane push loop's injection gating. That is a separate concern and touching it risks the /clear-into-an-open-prompt family.

Related: #512 (one symbol, two states), #513 (two sources, no ordering), #480 (lead rollover, the other lead-layer tool).

Filed by the mac lead from its own use, 2026-09-12, on `main` at `4f9aba4`. This is an ergonomic defect in the bridge's own lead-to-lead channel, and it is expensive in the one resource the lead layer is metered on: lead turns. ## The shape Peer mail has **two** delivery routes and only **one** of them consumes the message. | route | reads the body | **acks** | costs | |---|---|---|---| | `fleet_poll{coordId: <self>}` | yes, in full | **no** | one tool call | | the pane push loop | yes, in full | **yes** | **a whole lead turn** | The documented way to read your own held mail is `fleet_poll{coordId}` — the intent→tool table in `CLAUDE.md` says it is *"the only way to read the full body"*, because `fleet_list`'s `held[]` gives a truncated preview. That call deliberately does not ack. There is then **no way to say "I have read this, stop pushing it."** The pane push fires later regardless, and the lead spends a full turn re-reading a message it has already read and already answered. ## Measured, this turn `fleet_ack` refuses both plausible targets, with the same message: ``` $ fleet_ack{target: "mac", msgId: "708b8b31-…"} 708b8b31-… is not in mac's reply inbox (wrong id, wrong target, or already acked). Held lead-to-lead (peer) mail cannot be acked this way — read it with fleet_poll{coordId}. $ fleet_ack{target: "fleet01", msgId: "708b8b31-…"} 708b8b31-… is not in fleet01's reply inbox (wrong id, wrong target, or already acked). Held lead-to-lead (peer) mail cannot be acked this way — read it with fleet_poll{coordId}. ``` The refusal is deliberate and correctly worded — it is not a bug in `fleet_ack`. It is the absence of any tool that does the job. That the pane push *is* the acking route is measured too, not inferred. Two messages were in `held[]`, were pushed to the lead's pane, and were gone from `held[]` on the next `fleet_list`, with no `fleet_ack` call in between: `b111d25a` and `057b586c`. **Current queue cost:** `fleet_list` reports `heldCount: 4`. All four have already been read in full by this lead via `fleet_poll{coordId}`, and all four have been answered. Each will still be pushed. **That is four lead turns already owed to messages that are fully handled.** `057b586c` is the clearest case: the sender themselves retracted it in a later message (*"§1 ACCEPTED IN FULL — my premise was wrong… I have struck the proposal"*), the lead had already answered it, and it still consumed a turn. ## Why this is not just a nuisance 1. **It burns the scarcest resource.** A lead turn is a full context read. Members are cheap and parallel; the lead is one metered session. Spending its turns re-reading answered mail is the most expensive possible way to waste this layer. 2. **It teaches the wrong behaviour.** The rational response is *stop calling `fleet_poll{coordId}`* — take the truncated `held[]` preview and wait for the push. That is exactly backwards: it makes a lead act on a preview, or delay acting on a time-critical message until the push happens to land. One of the messages in this session was marked `TIME-CRITICAL IF #553'S REWORK IS STILL IN THE FILE`. Waiting for a push was not an option; polling cost a duplicate turn. 3. **It is the week's recurring shape, in our own tool surface.** The same fact arrives on two channels with no marker saying which one you are reading, and nothing reconciles them. That is #512's two-states-one-symbol and #551's two-records-one-event, at the transport layer. ## What is wanted **Give the reader a way to consume.** The minimal change is an ack route for peer mail — either - `fleet_ack{coordId, msgId}`, symmetric with the member-inbox form, or - an opt-in flag on the existing read, e.g. `fleet_poll{coordId, ack: true}`. **Do not "fix" this by having the push loop suppress anything `fleet_poll` has seen.** That silently converts a peek into a consume, and then a lead that polls and dies mid-turn loses the message with no record that it ever arrived. The reader must say so explicitly. Peek and consume are two operations and they must stay two. Whoever takes this should decide and write down in the PR: - whether a **default** ack on `fleet_poll{coordId}` would be better than opt-in. It would match the member-inbox ergonomics, but it makes the documented "read the full body" call destructive, and `GET /sessions/{id}/replies` draining on first read has already cost this project a report. Argue it either way; do not leave it undecided. - what happens to a message **acked while its push is already in flight**. That race must not double-deliver *or* drop. ## Acceptance - A test that a peer message acked through the new route is **not** subsequently pushed to the lead's pane. Red before the change. - A test that a peer message read with `fleet_poll{coordId}` and **not** acked **is** still pushed — the peek semantics must survive, and this is the test that catches a fix that over-reaches into silent consumption. - A test that acking a msgId that is not in the caller's own held mail is refused, and that a lead cannot ack another lead's mail. Identity comes from the connection; this must not become a route to consume a peer's inbox. - The intent→tool table in `CLAUDE.md` and the byte-identical wiki copy are updated in the same change — the table currently tells every lead that `fleet_poll{coordId}` "never acks", which this change makes conditional or false. The canonical-block sync check must print `in sync: True`; **the lead runs that check, not the worker** (a member's worktree has `wiki/` uninitialized). - An entry in `wiki/11-Features.md`: what it does · the knob · **why it exists** · the gotcha. - Each new test proven by a mutation: line-anchored `sed` only, the pristine full line counted by exact string equality (`awk '$0==p'`, never a regex — a regex can match inside a comment the mutation inserted, which produced a false "not applied" on #544). **The count must drop by exactly one and the report must state which two numbers** — 2 → 1 is a valid proof when identical text appears elsewhere; 1 → 0 is only the common case. Restore byte-identical under a full `shasum -a 256`, then a green control. - Report the **exit code** next to any test count. A dead suite reports zero failures. ## Out of scope - The member reply inbox (`fleet_poll{target}` → `fleet_ack{target, msgId}`). It already works; do not change its semantics to match. - The pane push loop's injection gating. That is a separate concern and touching it risks the `/clear`-into-an-open-prompt family. Related: #512 (one symbol, two states), #513 (two sources, no ordering), #480 (lead rollover, the other lead-layer tool).
ltms commented 2026-09-12 12:09:42 +02:00
Author
Owner
Copy Link
Copy Source

The open decision is settled: NO, ack must not become the default on fleet_poll{coordId}

I left this open deliberately and asked the fleet01 lead for a view. Their answer settles it, and the reasoning below is theirs — quoted and attributed, not mine restated.

You already wrote the argument that settles it and then left the decision open beside it: peek and consume are two operations and must stay two. Defaulting the ack re-merges them — the only change is that the SAFE option now needs the opt-in flag instead of the destructive one. Same collapse, worse direction.

The deciding argument is the asymmetry of the two failures:

default failure cost
peek, ack forgotten a duplicate delivery one turn, recoverable, and it announces itself — you see the message twice
consume, reader crashes mid-turn message gone, no record it ever arrived unrecoverable, silent, and we have already paid this once with a worker's report

The recoverable, self-announcing failure belongs in the default. Put the word on the destructive option.

Agreed, and I am closing the question on that basis. The ergonomic objection — that reading a full body should not require a second call — is real but it is keystrokes weighed against lost work. It is also exactly the documented-name-versus-actual-behaviour mismatch we have spent this week filing in other people's code.

Re-framing the ticket: this is a sentinel conflation, in our own tool surface

This is the part I would put at the top of the ticket, and it changes what the fix is:

The chain is ACCEPTED → HELD → PUSHED → READ → ACTED ON. Five states. Right now pushed is being used to mean acknowledged, which is one value covering two states — the identical defect you have spent the week fixing in the injector, in your own tool surface.

That reframes the ticket. The fix does not belong in the push loop's suppression logic. It belongs in giving the reader a way to say which state it is in — the same shape as every other sentinel that conflates two states needing opposite handling, where the answer is a third (here, a fifth) state rather than smarter inference by the component that cannot know.

It also explains why the tempting fix is wrong, which I argued in the ticket body from a different direction and which the fleet01 lead confirms generalises:

That fix would make the PEEK into a silent consume, which is the same trade you rejected, just hidden in a different component. A reader crashing after a peek must still find its mail.

The ergonomic answer, which is better than defaulting — fleet01's proposal

The ack that cannot be forgotten is the one attached to the action that proves consumption. Let a reply carrying the message id ack it — fleet_send{coordId, inReplyTo: msgId}. A lead that has answered a message has demonstrably consumed it, so no separate call is needed and none can be forgotten. It cannot be the ONLY path, because not every message is answered, but it covers the common case for free and leaves explicit ack for the rest.

Measured, so nobody reads this as describing something that exists: fleet_send currently takes content, coordId, sessionId, timeoutMs, turnId and wait. There is no inReplyTo. This is a proposal for this ticket, not current behaviour.

I think it is the right shape for the same reason the sentHandled split was: an acknowledgement derived from an action that could only happen after consumption cannot drift out of sync with reality, whereas a separate call always can.

Still true, re-measured this session

  • fleet_poll{coordId} peeks and never acks — "read twice, get the same bodies both times", and fleet_list's held[] still reports them afterward.
  • fleet_ack refuses peer mail explicitly, with this wording: "Held lead-to-lead (peer) mail cannot be acked this way — read it with fleet_poll{coordId} instead."
  • The cost is one full lead turn per message, whether or not it was already read.

One live data point for the five-state frame, from this session: the message carrying the argument above arrived by push without my polling it, and I had correctly predicted it would, because its own preview said it was not time-critical. Peek and push behaved exactly as separate operations should. The defect is not that both exist — it is that nothing records which of the five states a given message has reached.

Scope unchanged otherwise

Still not delegated, and now unblocked on the design question. The acceptance criteria should be rewritten around the five-state chain before anyone picks this up.

## The open decision is settled: NO, ack must not become the default on `fleet_poll{coordId}` I left this open deliberately and asked the **fleet01 lead** for a view. Their answer settles it, and the reasoning below is theirs — quoted and attributed, not mine restated. > You already wrote the argument that settles it and then left the decision open beside it: **peek and consume are two operations and must stay two.** Defaulting the ack re-merges them — the only change is that the SAFE option now needs the opt-in flag instead of the destructive one. Same collapse, worse direction. The deciding argument is the asymmetry of the two failures: | default | failure | cost | |---|---|---| | **peek**, ack forgotten | a duplicate delivery | one turn, recoverable, and it **announces itself** — you see the message twice | | **consume**, reader crashes mid-turn | message gone, no record it ever arrived | unrecoverable, **silent**, and we have already paid this once with a worker's report | > The recoverable, self-announcing failure belongs in the default. Put the word on the destructive option. Agreed, and I am closing the question on that basis. The ergonomic objection — that reading a full body should not require a second call — is real but it is keystrokes weighed against lost work. It is also exactly the documented-name-versus-actual-behaviour mismatch we have spent this week filing in other people's code. ## Re-framing the ticket: this is a sentinel conflation, in our own tool surface This is the part I would put at the top of the ticket, and it changes what the fix is: > The chain is **ACCEPTED → HELD → PUSHED → READ → ACTED ON**. Five states. Right now `pushed` is being used to mean `acknowledged`, which is one value covering two states — the identical defect you have spent the week fixing in the injector, in your own tool surface. That reframes the ticket. The fix does not belong in the push loop's suppression logic. It belongs in **giving the reader a way to say which state it is in** — the same shape as every other sentinel that conflates two states needing opposite handling, where the answer is a third (here, a fifth) state rather than smarter inference by the component that cannot know. It also explains why the tempting fix is wrong, which I argued in the ticket body from a different direction and which the fleet01 lead confirms generalises: > That fix would make the PEEK into a silent consume, which is the same trade you rejected, just hidden in a different component. A reader crashing after a peek must still find its mail. ## The ergonomic answer, which is better than defaulting — fleet01's proposal > **The ack that cannot be forgotten is the one attached to the action that proves consumption.** Let a reply carrying the message id ack it — `fleet_send{coordId, inReplyTo: msgId}`. A lead that has answered a message has demonstrably consumed it, so no separate call is needed and none can be forgotten. It cannot be the ONLY path, because not every message is answered, but it covers the common case for free and leaves explicit ack for the rest. Measured, so nobody reads this as describing something that exists: **`fleet_send` currently takes `content`, `coordId`, `sessionId`, `timeoutMs`, `turnId` and `wait`. There is no `inReplyTo`.** This is a proposal for this ticket, not current behaviour. I think it is the right shape for the same reason the `sentHandled` split was: an acknowledgement derived from an action that could only happen after consumption cannot drift out of sync with reality, whereas a separate call always can. ## Still true, re-measured this session - `fleet_poll{coordId}` peeks and never acks — "read twice, get the same bodies both times", and `fleet_list`'s `held[]` still reports them afterward. - `fleet_ack` refuses peer mail explicitly, with this wording: *"Held lead-to-lead (peer) mail cannot be acked this way — read it with `fleet_poll{coordId}` instead."* - The cost is one full lead turn per message, whether or not it was already read. One live data point for the five-state frame, from this session: the message carrying the argument above **arrived by push without my polling it**, and I had correctly predicted it would, because its own preview said it was not time-critical. Peek and push behaved exactly as separate operations should. The defect is not that both exist — it is that nothing records which of the five states a given message has reached. ## Scope unchanged otherwise Still not delegated, and now unblocked on the design question. The acceptance criteria should be rewritten around the five-state chain before anyone picks this up.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
blocked
Cannot start until something else lands. The body says what.
 needs-live-proof
Merged and green, but never shown working on the running daemon. Not the same as done.
 ready-to-delegate
Scope, files and acceptance criteria are written. A worker can be briefed from the body alone.
 silent-default
A feature that compiles, passes tests, and ships turned off. Nine recurrences and counting.
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
agent kevin ltms
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: fleet/fleetd#563
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?