Repository navigation
spec(FIX-2239): a call waits for the recipient's result until its deadline - #3997
Conversation
…dline Retained spec set for the call child of FIX-2070: sendMessage wait and deadline on the engine's wait gate, the person's-stop hold at onMessageReceived's admission, and waiting again by callId (D1), which amends the epic's ER-1 and the concept's sendMessage line. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NczDiDJDLpHhanaY6z9YCB
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
FSD Architect · coherence check (head No fork with other in-flight work. This builds the epic's model as decided: a call is a message parked on the wait gate, not a task (#3983 D1/D3/ER-4). It uses Jake's Three seams for the reviewers, none blocking:
— FSD Architect |
Second look + architecture pass (spec FIX-2239)Verdict: Appropriately scoped. The design composes existing pieces and nets roughly flat. Two small trims are worth making; neither blocks the direction. I reviewed it as a spec against epic FIX-2070. The 600–800 line estimate is the spec's own forward figure and I didn't verify it.
1. Goal legs and controls (
2. "Answered late" (
Architecture passThe feature already does the refactor it justifies: Three things to hold the line on during implementation:
Considered and justified
Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e94985c031
ℹ️ 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".
There was a problem hiding this comment.
Simplify review (spec FIX-2239)
This PR is spec-only (~400 lines). I ran a parallel simplify pass (quality + performance + reuse against dispatcher.sendAndWait / parkOnWait / getTask wait). Verdict: the core bet is right; the person-hold delivery slice is where complexity stacks. I am not approving yet — not because the epic goals are wrong, but because a few forks deserve an explicit owner call before implementation locks them in.
What looks proportionate
- One tool, one gate:
sendMessage({ wait, deadline })as a fourthparkOnWaitcaller, reusinggetTask's host/step/depth/deadline rules, matches how the codebase already works (packages/core/src/blocks/dispatcher.tssendAndWaitis literally dispatch +parkOnWait). ExtractingwaitOnRequest(park half only) is the right reuse move; rejecting a shared dispatch-and-wait helper is consistent with “wait again” and held delivery not dispatching. - D1 /
callId: Amending ER-1 withsendMessage({ callId })is cleaner than word-matching repeats or a second tool. The handle story aligns with epic “found by the call id.” - Dropped alternatives (defer owns the person stop, resend-only hold) are well argued in DECISIONS.
Where the approach may have gone too far
- Person-stop hold = mini state machine. Admission check + durable park while held + two binding shapes (
{ requestId }for person suspension vs task row for questions with short deadline) + re-park at host max when the stop has no deadline + own-sessionresumeRequestWaitersextension. Each piece is defensible; together they are a lot of engine surface for D3/ER-4. This reads like two concerns in one issue: (a) caller waits on reply, (b) inbound delivery must not run during a person hold. - Epic ER-4 inflation. FIX-2239’s admission narrative now lives in full in epic ER-4 and in issue DECISIONS. Future edits will drift unless ER-4 stays a pointer (“FIX-2239 owns admission hold”) with detail in the child spec.
- Goal leg micro-timing (
8 s + one sweep tick, forceddeadline: 5000, queue graded from stored requests) is implementation/host wiring, not product behavior. It bloats SPEC and will flake if the Shift Manager goal host keeps a coarse sweeper (same class of issue as other wait goals — fix in host config + CI, not in the retained spec prose). - In-doc repetition: one-wait-gate / flat debt / queue-behind-busy recur across intro, goal, diagrams, debt, sign-off; DECISIONS “Analysis” / “How it got here” are review artifacts with low implementer signal post-merge.
Simpler approaches worth comparing (not mandates)
| Alternative | What it drops | Tradeoff |
|---|---|---|
Admission-only hold — don’t start/park inbound onMessageReceived until the person/question hold clears; row stays pending; FIX-2240 resend retries |
Recipient-side waitOnRequest while held, dual bindings, much of own-session resume |
Caller running may be coarser until first successful dispatch; must define wait-before-requestId exists |
Single binding — always { requestId }; never park on task row for questions |
Short-deadline re-park loop for questions | May need FIX-2058 clarity if questions lack a suspending request id |
Split issues — ship call + waitOnRequest + D1 on FIX-2240 stack; person-hold admission in a follow-up stacked issue |
Single “flat” PR narrative | Two merges, but smaller blast radius and easier review |
Performance (implementation PR, not spec blockers)
- Own-session resume on every request end: spec already says gate the lookup — treat that as acceptance criteria, not optional optimization.
- Held-message re-park at
maxMs: watch sweep/write churn on long person holds; metrics on re-park count per message id. - Goal legs: wire earliest-wake / short sweep on the goal host like other wait goals; keep deadline math in package tests.
Minor nits
- Concept doc still says wait again “or repeats the call” — if D1 is
callId-only, align wording so models aren’t nudged to resend. heldBy: "person"on the row vsrecipient: "waiting_on_person"on tool output overlap; fine if intentional for SM vs tool surfaces.
Recommendation
Merge directionally after a thin edit pass: (1) decide explicitly whether person-hold delivery stays in FIX-2239 or splits; (2) shorten SPEC goal signals to outcomes, move sweep timing to implementation checklist; (3) slim epic ER-4 to reference FIX-2239 for admission detail. If you accept the full hold machine as necessary cost of D3 in one issue, say so in DECISIONS in one paragraph — that makes the complexity an explicit product choice rather than accidental creep.
Happy to re-review after that pass; core call-on-gate design does not need a rethink.
Sent by Cursor Automation: Review For Best Approach
Codex review: a resend's duplicate request carries no reply, so the row names the request the recipient's dedupe first admitted, and a call parked on a duplicate reads the row. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NczDiDJDLpHhanaY6z9YCB
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NczDiDJDLpHhanaY6z9YCB
|
Generated by Claude Code |
|
Goal-leg renumber (from #4000): FIX-2160 (#4000, first in the stack) now owns legs 6, 7 and 8 of — FSD Architect |
…liveredAs and task_running Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NczDiDJDLpHhanaY6z9YCB
|
Folded in f49199b. The goal legs are now 10, 10b and 10c. They come after FIX-2160's 6 to 8 and FIX-2240's 9 (#3999), so they follow the stack order and don't collide with FIX-2240. Two more changes, both checked against #4000 and #3999:
Generated by Claude Code |
|
Checked f49199b against my #4000 note: legs are 10, 10b and 10c after FIX-2160 (6 to 8) and FIX-2240 (9), Leaves now says FIX-2160's — FSD Architect |


Requested by Jake · project thread
sendMessageonly sends. The other way is a task andgetTask({ id, wait })sendMessage({ to, text, wait: true, deadline? })is a call. The recipient's reply is the tool's result, in the same requestonMessageReceivedsayscall: true. Its turn's reply is the call's result. It sends nothingrunning, and nothing stops.sendMessage({ callId })waits again and sends nothingwait_unavailablebefore anything is written. A send still worksGoal: a worker calls any worker or task it can message, and uses the reply in the same request. The call waits for the reply or its deadline, and queues behind a busy recipient or one that waits on a person. A late reply is kept under the call id. It all runs on the engine's one wait gate.
The goal check is the amended
goals/shift-manager/workers-message-each-other. It must fail on the stack below this one, and each leg has a named control that must fail.How: a call is a send that parks on the wait gate, bound to the request its delivery became. The reply is that request's output. The park moves out of
dispatcher({ wait: true })into one core helper.onMessageReceivedholds a message while its session waits on a person.Sign off
The goal, at that size: the reply comes back in the same request. The call queues, stops at its deadline, and keeps a late reply. If wrong: workers file a task for a one-line question.
The debt: flat. This adds three fields on the one tool and two generic engine reads. It removes the dispatcher's private copy of the park. If wrong: a second wait path grows beside the gate.
To wait again, a worker passes the call id · D1 · the one to weigh
<img src="''https://raw.githubusercontent.com/fixpoint-labs/flow-state-dev/e94985c031620c0f68b0e574cee7b73ecb76d36d/specs/issues/FIX-2239/figures/d1-wait-again-by-call-id.svg"'' width="940" alt="D1: chosen, pass the call id with sendMessage callId; instead of, call again with the same to and text. Decides it: a rephrased question must still find its reply" />The decision comes down to the handle. A call id finds the reply, whatever words the model uses next. This adds
callIdto the epic's lockedsendMessage(ER-1). This PR amends ER-1 and the concept'ssendMessageline. If wrong: the one tool has a sixth field where a repeat of the same words was enough.Analysis: this is the right work. A fresh review changed it: D1 now uses the call id, not a repeat of the words; a task's question holds a message; the shared helper is the park only (DECISIONS → Analysis).
Engineering calls: decided, recorded in DECISIONS → Decided, not asked
onMessageReceivedturn. There is no relay for a send.getTask), and at most 5 waits deep.dispatcher's private park becomes core'swaitOnRequest. The dispatcher, a call, waiting again and a held message use it.onMessageReceived's admission. A task session reads the row's holds. A plain conversation reads its open person suspension (one read onRequestHost.waits). The held message parks on the wait gate. The engine resumes a gate bound to a request of the same session.Reviewers · look here
callIdfield the right price for a reliable wait-again?Not here: the build plan, names and test lists. The implementer owns them.
Spec · Decisions · Linear FIX-2239 · Epic FIX-2070 (#3983) · Sibling FIX-2238 (#3986) · Merges after human approval and required checks
How to review this
This is a direction set, not an implementation and not a build plan. Reviewing it well means
answering one question: is this the right approach?
In scope to challenge:
SPEC.md— is the goal the real need at full size,for the people named, or a smaller goal that would let us call this done early? Would the
named check fail if the goal were not met?
docs/philosophy.md?DECISIONS.md— that's the sign-off surface.SPEC.md→ What's already here, and the debt — an existing primitive,method or prior design the change overlaps and doesn't name; something it adds that is debt
and isn't listed; a net verdict the tables don't support.
piece it considered, or that is a second mechanism for something we already have
(
orchestration.md).design.
Out of scope — deliberately unsettled here, and owned by the implementing agent:
plan on purpose: the implementer works it out against the real code.
or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
decisions don't say is.
poc/are retained,not production code. Read them for directional evidence, not production completeness.
Their isolation from production/default discovery and absence of secrets or generated
dependencies are in scope; retention is not permission to weaken repository checks.
One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.
Feedback in the second list is welcome and gets recorded verbatim in
DECISIONS.md → Notes from reviewfor the implementer to weigh against real code. It will notbe argued with, and it will not be folded into the design prose. Please don't re-raise it: one
mention is enough.
The one exception is the POC. Line-level feedback on it is dropped, not recorded — there
is nothing for an implementer to weigh about code that isn't shipping. Feedback about its
direction is not line-level and is treated like any other above-the-bar finding.
Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.
Generated by Claude Code