Skip to content

spec(FIX-2239): a call waits for the recipient's result until its deadline - #3997

Merged
jhoffner merged 4 commits into
mainfrom
spec/FIX-2239
Oct 27, 2026
Merged

jhoffner merged 4 commits into
mainfrom
spec/FIX-2239

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

A person who… Today After
builds a worker that needs an answer first Can't get it in the same request. sendMessage only sends. The other way is a task and getTask({ id, wait }) sendMessage({ to, text, wait: true, deadline? }) is a call. The recipient's reply is the tool's result, in the same request
writes the worker that is called Can't tell a call from a send onMessageReceived says call: true. Its turn's reply is the call's result. It sends nothing
calls a worker that is busy or waits on a person — The call queues. A request stopped for a person, or a task held on a question, counts as busy. At the deadline the caller goes on with running, and nothing stops. sendMessage({ callId }) waits again and sends nothing
runs a host that can't hold a wait — A call is refused wait_unavailable before anything is written. A send still works
watches Shift Manager A received message looks the same for every message The item marks a call. The Messages view shows if the answer came back

Goal: 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.

flowchart LR
  A["Shift Manager DevTeam · real model · fresh SQLite store"] --> L1["leg 6 · Helper A calls Researcher, then a task"]
  A --> L2["leg 6b · call and send into a session waiting on a person"]
  A --> L3["leg 6c · two waits in one step · call not settable"]
  L1 -->|"reply is the tool result, same request"| P["PASS"]
  L2 -->|"queued, deadline, then the kept reply"| P
  L3 -->|"refused before the row"| P
  C["control · FIX-2240's head, no wait"] -.-> L1
  L1 -.->|"under the control"| F["must FAIL · no call exists"]
Loading

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. onMessageReceived holds 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 callId to the epic's locked sendMessage (ER-1). This PR amends ER-1 and the concept's sendMessage line. 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
  • A call's result is the final text of the recipient's onMessageReceived turn. There is no relay for a send.
  • All checks come before anything is written: the host can hold a wait, the deadline is in bounds, one wait per model step (shared with getTask), and at most 5 waits deep.
  • dispatcher's private park becomes core's waitOnRequest. The dispatcher, a call, waiting again and a held message use it.
  • A call waits on the request that FIX-2240 records on the row.
  • The person's stop holds the message at onMessageReceived's admission. A task session reads the row's holds. A plain conversation reads its open person suspension (one read on RequestHost.waits). The held message parks on the wait gate. The engine resumes a gate bound to a request of the same session.
  • A parked caller or a parked message is never a person's stop.

Reviewers · look here

  • D1 against the epic's locked ER-1. Is a callId field the right price for a reliable wait-again?
  • The person-stop hold (DECISIONS → Decided, not asked). Does the message park on the wait gate keep the engine generic? Is anything admitted beside a person's stop?

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:

  • The goal and the problem framing in 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?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • The debt in 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.
  • Builds on / Adds in that same section — an Adds item that does not name the existing
    piece it considered, or that is a second mechanism for something we already have
    (orchestration.md).
  • A case a person would hit that the people table misses, when it would invalidate the
    design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • The build plan. Order, file-level changes, the test list, the PR split. The set has no
    plan on purpose: the implementer works it out against the real code.
  • Names, signatures, file paths, and module layout, beyond the few a decision locks.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Edge cases that don't change the approach. The implementer's tests own them.
  • Documentation wording. It is written at implementation, against what shipped.
  • Micro-optimizations and style preferences.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    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 implementation polish. Experiments under the owning spec's 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 review
for the implementer to weigh against real code. It will not
be 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

…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
@jhoffner jhoffner added the spec label Oct 27, 2026 — with Claude
@jhoffner jhoffner self-assigned this Oct 27, 2026
@vercel

vercel Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 27, 2026 9:34pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 27, 2026 9:34pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 27, 2026 9:34pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 27, 2026

Copy link
Copy Markdown

FIX-2239

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

Codex Review Summary

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-27T21:35:31.878930Z f49199b New commits
ℹ️ 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.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect · coherence check (head e94985c0)

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 onMessageReceived naming, and its question hold reads FIX-2058 ER-2's hasOpenHold. Pulling the dispatcher's private park out into one waitOnRequest reduces wait paths rather than adding one.

Three seams for the reviewers, none blocking:

  1. ER-1 amendment. callId changes a locked epic rule from a child PR, and FIX-2238 (#3986) has already merged against the five-field sendMessage. That's fine because the amendment lands in specs/epics/FIX-2070/DECISIONS.md here. FIX-2071's renames table (#3985) and the closure sweep (FIX-2249) should treat callId as a sixth field, not as drift.
  2. FIX-2240 is load-bearing and unspecced. "A call waits on the request FIX-2240 records on the row" depends on a spec that has no PR yet. If FIX-2240 doesn't keep the request id on the message row, this design has nothing to park on. FIX-2240's spec review should check that requirement against this PR.
  3. FIX-2241 (#3994). Its text says "only a person's suspension holds admission." This PR, and ER-4 as written, make a task's open question hold admission too. That doesn't cause a deadlock, because the filer answers with updateTask and not with a message into the held session. spec(FIX-2241): a task's midway question reaches its filer as a message #3994's wording should still match ER-4, so the two specs don't describe different admission rules.

— FSD Architect

Copy link
Copy Markdown
Collaborator Author

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.

# Finding Recommendation Est. Δ Sev Conf
1 The goal adds three legs and six new GOAL_CONTROL patches. Two of the checks can't be forced reliably Keep legs 6 and 6b and the controls no-person-hold, ignore-deadline, send-again. Move leg 6c, no-step-guard, no-default-deadline and relay-the-call into deterministic CI tests −110 / +35 Low Med
2 The Messages view tracks a third "answered late" state Show waiting and answered, both derived from the row and the reply. Drop the late distinction −40 Low Low

1. Goal legs and controls (goals/shift-manager/workers-message-each-other/)

  • The goal already carries six controls, and this spec adds six more, each patching a different module.
  • Leg 6c:one-wait-per-step needs a real model to make two calls in one step. The spec says it "fails if no second call was made", so it flakes on model behaviour, not on the code.
  • no-step-guard and no-default-deadline are deterministic. The spec already plans CI tests with red states for wait_too_deep and the other refusals, so a CI test covers them without a real model.
  • relay-the-call guards the "no second line" rule, which 6:no-second-line already asserts directly.
  • Cost: you lose real-model coverage of these four. They're mechanical, so a CI test fails them just as well.
  • Benefit: "PASS is every leg in 3 of 3 runs" gets cheaper with fewer flaky legs.

2. "Answered late" (packages/shift-manager, Messages view)

  • The epic only asks that FIX-2239 "shows a call waiting" (specs/epics/FIX-2070/DECISIONS.md:105).
  • "Answered late" needs a stored or derived deadline-versus-reply comparison and a third rendered state. Nobody has asked for it, and the kept reply is still returned.

Architecture pass

The feature already does the refactor it justifies: dispatcher({ wait: true })'s private sendAndWait splits so the park half becomes a shared core waitOnRequest, now used by the dispatcher, the call, waiting again and the held message. That passes the deletion test, because deleting it would reappear as four copies of the park. I found no other refactor this PR naturally justifies, so I'm not proposing more.

Three things to hold the line on during implementation:

  • waitOnRequest must stay the park only. Dispatch stays with each caller; the spec's "Split and shared" row says this, and the extraction should not grow a dispatch option.
  • The waits read and the wider engine resume lookup should stay generic (no heldBy/message-specific branching in engine), as the spec says.
  • The dispatcher's old private path should be deleted in the same change, not left behind a flag. The spec lists this under "Removes", so check the diff for it.

Considered and justified

  • The person-stop hold at onMessageReceived admission. Epic ER-4 and D3 require it, and "Considered and dropped" shows the lean alternative loses the call's request to wait on.
  • callId on sendMessage (D1), required by epic D1 and story M-02. Matching on words would cost more.
  • wait_unavailable, wait_deadline_out_of_range and wait_already_pending. They reuse getTask's rules by name and add no new mechanism.
  • The docs in five places. CLAUDE.md requires them. The changesets are borderline against BP-022, but workforce and core are published and gain public API.

Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread specs/issues/FIX-2239/DECISIONS.md Resolved

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 fourth parkOnWait caller, reusing getTask's host/step/depth/deadline rules, matches how the codebase already works (packages/core/src/blocks/dispatcher.ts sendAndWait is literally dispatch + parkOnWait). Extracting waitOnRequest (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 with sendMessage({ 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

  1. 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-session resumeRequestWaiters extension. 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.
  2. 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.
  3. Goal leg micro-timing (8 s + one sweep tick, forced deadline: 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).
  4. 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 vs recipient: "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.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2239/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2239/SPEC.md Resolved
Comment thread specs/issues/FIX-2239/SPEC.md Resolved
Comment thread specs/epics/FIX-2070/DECISIONS.md Resolved
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

Copy link
Copy Markdown
Collaborator Author

Typecheck & Test failed on e94985c, which is no longer the head. It is the summary job: its input jobs were cancelled when the later pushes started a new run, and it fails on cancelled. CI on the current head (185560c) is still running. This PR changes only spec and design docs, so no fix is needed.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Goal-leg renumber (from #4000): FIX-2160 (#4000, first in the stack) now owns legs 6, 7 and 8 of goals/shift-manager/workers-message-each-other/ (its DECISIONS.md, Decided, not asked, at 265c807). This PR's legs should renumber from 9 so the three siblings don't collide. Also note: #4000 decides `task_running` as a send-time refusal, so a call to a running coder task is refused before it ever reaches this queue; it is not a busy session.

— FSD Architect

…liveredAs and task_running

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiDJDLpHhanaY6z9YCB

Copy link
Copy Markdown
Collaborator Author

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:

  • Leaves now says a call to the coder's open task is refused task_running at send time. It never queues here.
  • The acting request is named as FIX-2240's deliveredAs.

Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

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 task_running refuses a call to the coder's open task at send time, and the acting request is FIX-2240's deliveredAs. That matches what I asked for, and there's still no fork.

— FSD Architect

@jhoffner
jhoffner merged commit 17cf6b8 into main Oct 27, 2026
13 checks passed
@jhoffner
jhoffner deleted the spec/FIX-2239 branch October 27, 2026 21:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants