Repository navigation
spec(FIX-2159): a person's running turn hears the tasks that finished while it ran - #3799
Conversation
… while it ran SPEC.md, DECISIONS.md, four figures, and a POC showing a running turn can take a settled notice through FIX-2123's take record, exactly once. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KqvMDt8EZazonAu2Vjvsg4
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
|
@codex review Please pay special attention to:
Generated by Claude Code |
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. |
|
Coherence read at 42a1ce7: no fork. This matches FIX-2159 as narrowed in #3797. The lab flow owns only the loop, the package adds a public take that runs FIX-2078's one ending path through FIX-2123's take record, plus an answer-again hook. FIX-2086's steer entry stays task-only, and messages stay with FIX-2070. That lines up with FIX-2153 #3788 too. One ordering condition: this cites the FIX-2152 D2 and ER-6 text as amended in #3797, so #3797 should merge before or with this PR. — FSD Architect |
jhoffner
left a comment
There was a problem hiding this comment.
Second look + architecture pass (direction-level only)
Overall: the approach holds. Reusing FIX-2123's take record (D1) and gating on isUserTurn (D2) are the lean choices, and I checked that isUserTurn is set only on the agent-user-turn door (agent-worker-flow.ts ~L1329), so the D2 gate is sound as described. Findings below, ranked.
1. The spec contradicts itself on crash behaviour (above the bar)
SPEC.md→ "Not done if": "a crash loses it".DECISIONS.mdD1 → Locks in: "A process death between the acknowledgement and the line drops the line, as it does today."
Both can't hold. Pick one and say it in the goal. If at-most-once is the intended trade (line after ack, so a crash never duplicates), reword "Not done if" to "heard twice", and say plainly that a result can be silently never shown after a crash. If the goal really is no loss, the line has to be written before the ack, and then takeover can re-say it, so the "heard once" check needs an idempotency key on the line item. As written, the people table's "loses the process mid-reply: never heard twice" is true but incomplete next to the goal text.
2. Two "answer once more" mechanisms in one flow, with unspecified order (above the bar; echoes the Codex ask)
run = board.planned(answeredRun) already answers once more after the plan (FIX-2076). The spec lists it under "Builds on" but never says where the new hook sits relative to planned: inside answeredRun (so it runs per plan step and each step gets up to 3 extra answers), or outside it (once per request, after the plan's answer)? Those give different behaviour for the very case the goal check uses (a worker that files two tasks and plans). The spec needs one sentence fixing the position and one sentence on how the bound of 3 interacts with the plan's own answer.
Architecture opportunity (the PR is the natural moment): this is the second bounded re-answer loop in the same flow. Rather than adding a parallel loop with its own constant, have the implementer look at whether planned's loop and the new hook can share one bounded "answer again" step (hook supplies the message, planned supplies its own). If they can't share, the spec should say why, so the next reader doesn't find two loops and wonder. I'd keep this a note for the implementer, not a design change.
3. The hook runs in every entry that shares run
run is shared by the user door, the task entry, and board.entries(run) (notice-woken turns). If the hook is wired into run, it fires in task and notice turns too, relying entirely on the take returning [] outside a user turn. That is safe by D2, but then the app's hook runs (and an app that does more than take, e.g. its own logic) in turns the spec says are "unchanged". Either place the hook only on the agent-user-turn sequencer, or state that the hook is called on all entries and must tolerate it. The first is simpler and matches "only a person's turn".
4. Leaner shape worth one line in DECISIONS (optional)
D3 rejects "package reads before every call" and "all in the lab", but not a single option on the flow that turns the behaviour on (package owns take + one bounded re-answer, the app only opts in). It loses on "the loop is invisible to the app", which Jake prefers, so the rejection is probably right. But it would be the smallest public surface (one flag instead of a hook plus a take), so it deserves a named row in "Considered and dropped" with that reason, rather than being absent.
5. Housekeeping
- PR description: the D3 and D2 figure embeds are malformed (
<img src="''https://…inside code fences), so they render as code instead of images. Only the D1 and "what changes" figures render. The SPEC/DECISIONS files embed fine; this is only the PR body. - Ordering: as the FSD Architect noted, this cites #3797's amended D2/ER-6, so #3797 must merge first or with this.
- The POC covers the take record only (it says so). The three things the spec leans on that it does not exercise: Error Reporter stop-before-ack, the answer-again bound, and the interaction with
planned. Fine for direction, but the implementer's tests should own #2 above explicitly.
No change requested to D1 or D2. Items 1 and 2 are the ones I'd want resolved before approval; 3 and 4 are for the implementer or a line in DECISIONS.
Generated by Claude Code
…e plan's answer Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KqvMDt8EZazonAu2Vjvsg4
There was a problem hiding this comment.
Simplify review
Problem this spec solves: When a person’s reply is still running and a delegate task finishes, the result should show up in that same reply (once), and the model should get another beat to use it—without a second request and without double-hearing.
Verdict: Approve. The chosen decomposition is the smaller change set among the realistic options: reuse FIX-2123’s take record (D1), gate on isUserTurn (D2), reject a hidden package loop and a prepareStep/steer-style reader (D3), and keep one Workforce ending path instead of a second mark or a public “list finished tasks” API. Bulk in the diff is mostly retained-spec ceremony (decision SVGs, POC harness)—not extra product surface.
The main complexity tax is intentional and already surfaced in sign-off: two public entries (hook + take) with no default hook body, so every app that wants Claude Code–style behavior copies the same snippet. That is defensible vs rejected option (b) (package-owned invisible loop), but there is a middle ground worth one paragraph in Considered and dropped: a default answerAgain implementation on defineAgentWorkerFlow that calls takeFinishedTasks and formats lines, still overridable—same visibility, less copy-paste. I would not block merge on that; it is a product default call.
Implementation risks to carry into the build PR (not spec blockers):
- Discovery algorithm —
takeFinishedTasksdoes not say how to find owed rows; the obvious analogue is full-boardlist()+ metadata scan + per-candidategetCommitted, up to ~4× per turn (initial + three re-answers). ReuseowesAnyNoticeprefilter and avoid double scans; consider a per-invocation work cap if many tasks complete at once. - Forking
task-settled.ts— D1/D3 require the same order as queued handling; factor one internal delivery mode (queued-turnvsin-running-turn) rather than duplicating the sequencer. - Queued
onTaskSettledstill runs — correct for crash/no-hook paths; expect N cheap admits during long replies, not unbounded memory (existing defer caps).
Doc / POC tighten-ups (optional before or after merge):
- Settled duplicates POC README verdict bullets; link README for evidence depth.
- D3 in Settled cites a POC “control” for read-without-take; README says that control is manual (remove clear, re-run)—either label it argument + manual control or add a fourth automated test.
- D2 is epic/
isUserTurnreasoning, not POC-exercised—one line saying so avoids implying parity with D1 evidence. - “Decided, not asked” notice taxonomy largely restates
task-settled.ts; a single cross-ref may be enough unless a prior review needed the enumeration.
Skipped (needs owner, not simplify-in-spec): dropping per-decision SVGs (sibling-spec pattern), promoting POC to integration-tests (contradicts retained specs/**/poc policy), merging with FIX-2154’s opposite mid-turn rule for messages (correctly kept separate).
No production code in this PR; direction looks right to merge after the usual spec gate.
Sent by Cursor Automation: Review For Best Approach
|
Second-look review, addressed in f5efeb9:
Ordering: #3797 merges first or together with this PR, as the links line says. Generated by Claude Code |
|
Follow-up to the coherence note above. No fork, and D3 as written is the Architect pick: the take stays on FIX-2078's one ending path and the loop is code the app can see. Option (b) would add a read before every model call alongside steers. Asks:
— FSD Architect |
…recorded Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KqvMDt8EZazonAu2Vjvsg4
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 42a1ce7ee6
ℹ️ 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".
…scope is rows still owing a notice Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KqvMDt8EZazonAu2Vjvsg4
|
@codex review At 74b5efa: the POC now follows the take, acknowledge, line order, with cases 4, 4b and 5 added or reworked. The take's scope is now rows that still owe a notice. Please check that the at-most-once claim in D1 matches what the POC asserts. Generated by Claude Code |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
…xported bound, planned, D2 edges, messages Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KqvMDt8EZazonAu2Vjvsg4
|
It's not clear if this is saying that this is just a flow factory, and we're including a block to allow the ability to check tasks and then rerun back to the beginning again. were we planning to make this a block? |
|
All five asks from the Architect follow-up are folded in at 53b8593, each checked on
The red "Typecheck & Test" on 42a1ce7 was the aggregator for a run my next push cancelled ( @codex review: please look hardest at the bound in item 3 (the hook isn't run after the last answer, and the take refuses at the bound) and at whether the shared-handling factoring in item 2 keeps the routed path ( Generated by Claude Code |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KqvMDt8EZazonAu2Vjvsg4
|
Jake, you read it right, and that's how the spec was written: an option on the flow factory plus a plain function, neither of them a block. That was inconsistent, because the factory's sibling slot
Making them blocks puts them in the trace, and it lets an app compose the take, since a handler can't call one (BP-011). The SPEC diff example and D3's "Locks in" now say this. If you'd rather the loop itself be a block the app wires in, instead of the factory going back to the turn, say so. I'd keep it in the factory, so the bound can't be bypassed. Generated by Claude Code |
|
Revising the D3 pick from my two earlier notes. After a second look, Jake and I agree the answer-again hook is a new mechanism we already have.
Asks:
The rule this follows: a new behaviour is built from the blocks and pieces we already have, not from a new package mechanism. — FSD Architect |
…block is a source, the take the only new behaviour Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KqvMDt8EZazonAu2Vjvsg4
… job needs a project; review nits The answer-again hook is dropped (#3799 review): the lab reuses the step Planning.planned runs, under one cap. ER-8 states the invariant and lets each lab say when it asks (FIX-2154 at the first job that touches files). Footer counts three gaps; provenance note shortened; harness tag reads the worker setting. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv
|
This revision is folded in at c073036. One ask couldn't be done as written, so I adapted it. I also checked two claims on main, and both need correcting. Done.
Adapted: ask 1, drop the hook. No version of this works without some slot. So the spec keeps Two corrections, from main:
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: c073036688
ℹ️ 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".
|
Checked c073036 against my asks, and the adaptation is accepted.
The extra call on task and notice turns is fine as written: the take hands over nothing outside a person's turn. No fork with in-flight work, and nothing more from me on D3. — FSD Architect |
…knowledgement Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KqvMDt8EZazonAu2Vjvsg4
| installation, | ||
| + // What else the worker answers about, in the same request: anything that finished while it ran? | ||
| + // Fed to the answer-once-more step the plan already uses. A message, or nothing to stop. | ||
| + answerAgain: sequencer({ name: "lab-answer-again" }) |
There was a problem hiding this comment.
I didn't mean for the config to require a block. That's a bit messy, unless we want to at least provide that block as a pre‑built factory. Or we could just say true, and then it would provide the default factory. So yeah, I actually do like that answer. The block can be overridden, but we don't have to provide the block as a means for it to exist in the first place. I just meant make sure it actually is a block under the hood.
There was a problem hiding this comment.
Done in dacb532. answerAgain: true now uses the package's pre-built block, which comes from an exported factory: take what finished, then turn the lines into a message. If an app wants its own wording, it passes a block to replace it, either the factory with an option or its own sequencer around takeFinishedTasks. In both cases a block runs underneath, but the app never has to write one.
I updated the SPEC diff, D3's Locks in and the sign-off line to match. The earlier review note about a default helper is marked as adopted.
Generated by Claude Code
…rrides it Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KqvMDt8EZazonAu2Vjvsg4
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KqvMDt8EZazonAu2Vjvsg4
…delegated workers (#3803) * spec(FIX-2152): amend for a lab's working directory and a harness on delegated workers ER-8: a lab works in a project, picked per session or configured per worker, never its own checkout; with none set it asks. FIX-2161 lets an ordinary session open on a project. ER-9: only delegated workers run on a coding harness, chosen by config (one lab worker flow per harness). Set, flow, debt and the ownership figure updated. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv * spec(FIX-2152): lead measure of 18; FIX-2161 also covers a worker's default conversation The three lab amendments added steps (7, 6 and 5). FIX-2154 needs one project per worker on its default conversation, which FIX-2161 now covers. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv * spec(FIX-2152): ER-9 is one coding worker flow routed by a WORKER.md harness setting; ER-8 has one owner Settles the ER-1 cap against ER-9 by composition: one flow builds a manager per harness and routes by the worker's own setting, so the flow count stays flat. FIX-2161's per-worker case reads as the roster owner. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv * spec(FIX-2152): one package piece for D2 (the take); ER-8 asks when a job needs a project; review nits The answer-again hook is dropped (#3799 review): the lab reuses the step Planning.planned runs, under one cap. ER-8 states the invariant and lets each lab say when it asks (FIX-2154 at the first job that touches files). Footer counts three gaps; provenance note shortened; harness tag reads the worker setting. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv * spec(FIX-2152): FIX-2161 sets a worker's project from the screen, stored server-side Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv * spec(FIX-2152): the package's answer-again step runs the loop; projects need membership, not read Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv * spec(FIX-2152): D2 figure names the shared step as the loop Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv * spec(FIX-2152): D2 note, FIX-2159 row and Adds name the answerAgain slot and shared step Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KwpAiiUuq5pNkkmtNnc5pv --------- Co-authored-by: Claude <noreply@anthropic.com>


Requested by Jake · project thread
spec(FIX-2159): a person's running turn hears the tasks that finished while it ran
answerAgain: trueon the agent flow, or passes a block to change the wordingGoal: a person who asks the main session for work that starts background tasks sees the first result inside the reply that still runs, once, and that reply uses it.
The check reads the session's items, not the take record. Check:
goals/hand-offs/result-reaches-the-running-turn/, real model, controlGOAL_CONTROL=read-only(and today'smain). Why this goal: SPEC.md.Top row is today. The middle row takes the result when the answer ends and answers again in the same request.
How: one answer-again step, not two.
planned(FIX-2076) already answers once more after a turn in the same request; that step is extracted and gets a second source, finished tasks, under one exported cap. The app turns it on withanswerAgain: true, which uses a pre-built block, or passes a block to override it. The only new behaviour in the package is the take. The take gives what finished, once, through the take record thatonTaskSettledalready writes (FIX-2123). The default block calls it and turns the lines into the message.Why this needs a package change (Jake's lab-flow build, tested first): what the worker answers about stays in the lab's flow, and the answering reuses the step
plannedalready runs. The take does not fit in a lab. Nothing public takes a notice, andafterAnswercannot answer again. If the lab only reads finished rows, the notice stays owed, and the queuedonTaskSettledsays the line and wakes a second turn after the reply: heard twice. If the lab takes the notice itself, it must also report failures, dedupe and free the delegate's session. That is package work in the lab (ER-4).Sign off
The goal, at that size. If wrong: step 4 passes while the person sees the result twice.
The debt: up, a little. A public take and a source slot on the answer step
plannedalready runs, nothing removed. If wrong: two callers of one ending handling that someone must keep in step.The app's block feeds the one answer-again step
plannedalready runs; the package adds only the take · D3<img src="
https://raw.githubusercontent.com/fixpoint-labs/flow-state-dev/c07303668839f82a35b5fb25a1c0379a77d310d3/specs/issues/FIX-2159/figures/d3-app-flow-answers-again.svg"width="940" alt="D3 trade-off: the app's block feeding the shared answer step and the package take, chosen, beside all in the lab and the package reading before every model call; decided by each result heard once" />It comes down to hearing each result once: the lab alone can read a result, but cannot take it. A hook with its own loop and cap lost too: it would be a second way to answer again beside
planned's. If wrong: a factory option stands where a public way to compose the person's door should be.The take is FIX-2123's take record, in the turn's name · D1
It comes down to one mark. A POC on the real engine shows exactly-once in all three orders, and goes red without the turn's clear. The take never reads or writes the running-filer hold. If wrong: a result taken in the turn has weaker guarantees than one after it.
Only a turn that a person's own message started can take a result · D2
<img src="
https://raw.githubusercontent.com/fixpoint-labs/flow-state-dev/c07303668839f82a35b5fb25a1c0379a77d310d3/specs/issues/FIX-2159/figures/d2-person-turn-only.svg"width="940" alt="D2 trade-off: only a turn a person started, chosen, beside any running request; decided by never skipping the task ending work" />It comes down to the task's own ending work (
admitOwnTask): a take in a task session can skip it. If wrong: workers on tasks wait for results that Claude Code shows at once.Open: none. D3 is the one to weigh. Reasoning and what lost: DECISIONS.md.
Reviewers · look here
answerAgain: true(or a block) on the shared answer step the right public shape? The person's door is built inside the factory, so without a slot an app has nowhere to put a block after the turn.onTaskSettledrequest. Does anything read it as "the notice entry delivers this"?Not here: a result before every model call (dropped in D3), and messages from other workers, including FIX-2070's
{ session: id }form (not an ending).Spec · Decisions · POC · Linear FIX-2159 · epic FIX-2152 (D2 and ER-6 as amended in #3797) · builds on FIX-2123, FIX-2078 · merges after human approval and required checks
How to review this — altitude, what's in scope, what's deliberately unsettled
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.
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 with Claude Code
https://claude.ai/code/session_01KqvMDt8EZazonAu2Vjvsg4