Skip to content

spec(FIX-2159): a person's running turn hears the tasks that finished while it ran - #3799

Merged
jhoffner merged 10 commits into
mainfrom
spec/FIX-2159
Oct 23, 2026
Merged

jhoffner merged 10 commits into
mainfrom
spec/FIX-2159

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

spec(FIX-2159): a person's running turn hears the tasks that finished while it ran

Someone who… Today After
asks the main session for work that starts two background tasks Sees the first result after the reply ends, in a second turn Sees the result in the reply that still runs. The same reply answers again with it
builds an app on Workforce and wants this Can't. Nothing public takes a result Sets answerAgain: true on the agent flow, or passes a block to change the wording
has a worker on a task, or two workers talking Results come after the turn No change
gets a failed result that the Error Reporter did not take yet Heard after the turn No change
loses the process during the reply Never heard twice; a death after the dedupe write, just before the acknowledgement, drops the line Same, both ways (at most once)

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

flowchart LR
  I["main worker · real model · files two tasks to a fast delegate"] --> M["leg 1 · first ending lands while the reply runs · leg 2 · second lands during the answer again"]
  M --> S["the session's items"]
  S -->|"each result line in the respond request, once, then text that uses it"| P["PASS · goal met"]
  C["control · the app reads without taking"] -.-> M
  S -.->|"under the control"| F["must FAIL · the result is said twice"]
Loading

The check reads the session's items, not the take record. Check: goals/hand-offs/result-reaches-the-running-turn/, real model, control GOAL_CONTROL=read-only (and today's main). Why this goal: SPEC.md.

Three timelines of one person's turn: today a second request answers; after, the same request takes the result at the answer end and answers again; a second ending loops once more

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 with answerAgain: 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 that onTaskSettled already 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 planned already runs. The take does not fit in a lab. Nothing public takes a notice, and afterAnswer cannot answer again. If the lab only reads finished rows, the notice stays owed, and the queued onTaskSettled says 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 planned already 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 planned already 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

The existing take record, chosen, beside a new taken-in-R list. Decides it: one mark that the queued entry already obeys

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

  • Decisions → D3. Is 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.
  • Decisions → D1. The take record now names a conversation request or an onTaskSettled request. Does anything read it as "the notice entry delivers this"?
  • Spec → what stays. A result that lands during a long tool loop waits for that answer to end. Is that acceptable for step 4?

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:

  • 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.
  • 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 with Claude Code

https://claude.ai/code/session_01KqvMDt8EZazonAu2Vjvsg4

… 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
@vercel

vercel Bot commented Oct 23, 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 23, 2026 11:39pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 23, 2026 11:39pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 23, 2026 11:39pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 23, 2026

Copy link
Copy Markdown

FIX-2159

@jhoffner jhoffner self-assigned this Oct 23, 2026

Copy link
Copy Markdown
Collaborator Author

@codex review

Please pay special attention to:

  • D1: reusing FIX-2123's noticeTaken: record for a conversation request as the taker. Does anything (deliveredAsNotice, wait-on-task.ts, the pass's resend, owesUntakenNotice) read the record to mean "an onTaskSettled request delivers this" in a way a taking conversation turn would break?
  • D3: whether an answer-again hook on defineAgentWorkerFlow composes with board.planned (the plan's answer-once-more) without double answers or a turn that never ends.
  • D2: whether isUserTurn is a sound gate for "a session no task backs", including a coordinator's round-0 post.

Generated by Claude Code

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 23, 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-23T23:41:07.010300Z 39066bc 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

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 jhoffner left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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.md D1 → 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 (&lt;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

@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

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):

  1. Discovery algorithm — takeFinishedTasks does not say how to find owed rows; the obvious analogue is full-board list() + metadata scan + per-candidate getCommitted, up to ~4× per turn (initial + three re-answers). Reuse owesAnyNotice prefilter and avoid double scans; consider a per-invocation work cap if many tasks complete at once.
  2. Forking task-settled.ts — D1/D3 require the same order as queued handling; factor one internal delivery mode (queued-turn vs in-running-turn) rather than duplicating the sequencer.
  3. Queued onTaskSettled still 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/isUserTurn reasoning, 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.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2159/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2159/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2159/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2159/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2159/SPEC.md Resolved

Copy link
Copy Markdown
Collaborator Author

Second-look review, addressed in f5efeb9:

  1. Crash behaviour. It is at most once, which is today's order: acknowledge, then the line. The goal's "Not done if" and the people table now say so. A death before the acknowledgement is taken over after the turn; a death after it drops the line. There is no idempotency key.
  2. Hook vs planned. The hook sits on the agent-user-turn door, after run. That means it runs after the plan's own answer, once per request. Each answer again is one more turn of run. The bound of 3 counts only those answers. The idea of sharing one bounded step with planned is recorded in Notes from review for the implementer.
  3. Entries sharing run. This is resolved by (2): the app's hook never runs in task or notice turns.
  4. One-flag shape. It is now a named row in Considered and dropped, with its reason.
  5. Body figures. The PR body editor keeps wrapping two of the image URLs in backticks. These are the D3 and D2 figures:

D3``

D2```

Ordering: #3797 merges first or together with this PR, as the links line says.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

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:

  1. Keep D1 the one take record. The take should go only through takeNotice/noticeTakeWrite (orchestration/src/tasks/collection/internal.ts:307, notice/task-notice.ts:267) with by: R. No new metadata key, and no reads or writes of held or deferred…whileRunning. Please say this in "What's already here", so a later collapse of held/noticeTaken/whileRunning into one marker stays possible. Also note that the queued copy, turned away with whileRunning: R while R runs (task-settled-entry.ts:186-191), then finds the marker cleared and does nothing.
  2. "Two ways to hear an ending" is one handling with two callers. Please name the factoring: the report → dedupe (noteSeen) → acknowledge part of conversation-board/task-settled.ts:300-360 becomes one function that both the queued settle and the take call. Only where the line goes differs (said here and handed back, vs. wake-turn).
  3. The bound. It doesn't repeat core maxSteps (core/src/types/model.ts:259, the tool loop) or MAX_PASS_ROUNDS (conversation-board/board.ts:687, drain rounds). Please (a) make it one named, exported constant, and (b) say the take doesn't run after the last allowed answer, so endings stay owed for the queued onTaskSettled. Otherwise a fourth look takes lines that no answer uses. (c) Say how the hook combines with FIX-2076's planned (board.ts:1711-1717, plan.ts:13-19): does an answer-again run inside planned, can it file steps, and does a plan's extra answer count toward the 3?
  4. D2 edges. The mark is also set on the coordinator's round-0 post (standing-rules/user-turn.ts:6-8). Say whether that turn may take. A turn resumed after waitForUser keeps the mark, but while it's parked the queued copy isn't held (task-settled-entry.ts:181-184), so endings during a park go the queued way. Please confirm that's intended.
  5. FIX-2070. Add one line that a message, including the coming { session: id } form, never goes through this take (it isn't an ending, per FIX-2103), so FIX-2070's spec doesn't widen it.

— FSD Architect

…recorded

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KqvMDt8EZazonAu2Vjvsg4

@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: 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".

Comment thread specs/issues/FIX-2159/DECISIONS.md Resolved
…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

Copy link
Copy Markdown
Collaborator Author

@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

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

@jhoffner jhoffner added the spec label Oct 23, 2026
…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
@jhoffner

Copy link
Copy Markdown
Collaborator Author

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?

Copy link
Copy Markdown
Collaborator Author

All five asks from the Architect follow-up are folded in at 53b8593, each checked on main first:

  1. One take record. The take goes only through takeNotice with by: the turn's request. It adds no metadata key and never reads or writes heldFor or whileRunning. "What's already here" now has a row for this, which leaves room to fold them into one marker later. It also notes that the queued copy, turned away with whileRunning: R, finds the notice cleared after R and does nothing (task-settled-entry.ts:181-191).
  2. One handling, two callers. The end, report, noteSeen and acknowledge part of settle (task-settled.ts, about 320-345 on main) becomes one function that settle and the take both call. The only difference between the callers is where the line goes. This is in the debt table and in D1's Locks in.
  3. The bound.
    • It is one named, exported constant, separate from maxSteps and MAX_PASS_ROUNDS.
    • After the last allowed answer, the hook isn't run and the take hands over nothing, so later endings stay owed for the queued onTaskSettled.
    • The hook runs outside planned (it wraps the planned(answeredRun) result). An answer-again may file steps, and those are drained and answered in the same request. The plan's own answer doesn't count toward the 3.
  4. D2 edges.
    • The coordinator's round-0 post passes the gate (coordinator-flow.ts:768). This issue adds no hook to the coordinator flow, though, and its delegates' answers are routed, which the take never hands over.
    • An ending during a park goes the queued way. The take runs only in a running request, which is intended.
  5. Messages. One line under "What stays": a message never goes through the take, including FIX-2070's { session: id } form, because it isn't an ending (FIX-2103).

The red "Typecheck & Test" on 42a1ce7 was the aggregator for a run my next push cancelled (test "cancelled" = success). It was not a real failure.

@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 (settleConversationResult) out of the take.


Generated by Claude Code

@chatgpt-codex-connector

Copy link
Copy Markdown

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

Copy link
Copy Markdown
Collaborator Author

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 afterAnswer already takes a block. As of a8c0d7f, both pieces are blocks:

  • answerAgain is a block slot on defineAgentWorkerFlow, like afterAnswer. Its output is the next message, or nothing to stop.
  • takeFinishedTasks is a handler block the workforce package exports. The lab's slot is a small sequencer: take, then turn the lines into a message.
  • Going back to the worker's turn is the factory's job, bounded at 3. The app's block only decides whether there is a message.

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

@jhoffner

Copy link
Copy Markdown
Collaborator Author

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.

Planning.planned (FIX-2076, packages/workforce/src/conversation-board/plan.ts) already wraps a turn: the turn runs, its steps drain in the same request, and then the worker answers once more, told how each step ended. That's the shape this spec wants, triggered by steps instead of settled tasks. It's composed from core sequencer/doWhile blocks, like the board's round loop (MAX_PASS_ROUNDS, board.ts:687). A hook on defineAgentWorkerFlow with its own cap of 3 would be a second "answer again" with a second limit.

Asks:

  1. Drop the hook on defineAgentWorkerFlow. The lab's flow composes existing blocks: the turn, then a handler block calling the public take, then the answer-again step.
  2. One answer-again step. Extract the answer-once-more step planned uses into one block both callers use (steps finished, or tasks settled), with one cap, rather than adding a parallel one. If that can't work, say why in the spec.
  3. The only package addition is the public take (FIX-2123's take record through FIX-2078's one ending path), as in my follow-up's ask 1. Asks 2, 4 and 5 from that follow-up still apply. Ask 3 (the cap) moves to the shared step.
  4. Update D3 and the debt line. With this cut there's one way to answer again, not two.

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
jhoffner pushed a commit that referenced this pull request Oct 23, 2026
… 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

Copy link
Copy Markdown
Collaborator Author

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.

  • One answer-again step (asks 2 and 4). planned's answer-once-more step is extracted into one block with two sources: the plan's ended steps and the app's block.
    • It has one exported cap, built on core doWhile like the round loop, and the plan's answer counts toward it.
    • An answering turn files no step for itself. That's the rule planned already has (PLAN_ANSWERING_STATE).
    • D3 now rejects "a hook with its own loop and cap" as a second way to answer again. The debt line, the figures and the PR body are updated to match.
  • The take is the only new behaviour (ask 3). Follow-up asks 2, 4 and 5 still apply, and the cap moved to the shared step.

Adapted: ask 1, drop the hook. No version of this works without some slot. defineAgentWorkerFlow builds the person's door internally (agent-user-turn = markUserTurnStep → run, agent-worker-flow.ts:1330). Its only post-answer seam is afterAnswer, a .sideChain that can't answer. A lab using the factory has nowhere to put "the take, then answer again" after the turn.

So the spec keeps answerAgain, but only as a source for the shared step. It adds no loop and no cap. It runs wherever planned runs. Outside a person's turn the take hands over nothing (D2), so there the step answers only for the plan, as today. D3's "what would change my mind" names the alternative: a public way to compose the agent flow's door would remove the slot too.

Two corrections, from main:

  • planned isn't built on doWhile and has no cap. It is .step(turn).tap(decidePlan).stepIf(owesPlan, …, answer) and answers exactly once (plan.ts:365-389). So the cap is new to that step, not shared from it.
  • Feeding the app's source into planned means it runs on task and notice turns too, where it costs one call that returns nothing. The spec says this under "Where it runs".

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

Comment thread specs/issues/FIX-2159/DECISIONS.md Resolved
@jhoffner

Copy link
Copy Markdown
Collaborator Author

Checked c073036 against my asks, and the adaptation is accepted.

  • Ask 1, adapted. You're right. On main the person's door is built inside the factory (agent-user-turn at agent-worker-flow.ts:1330), and afterAnswer is a .sideChain that can't answer. answerAgain as a source into the shared step, with no loop and no cap of its own, is the smallest slot that works. It sits beside board.planned(answeredRun) (:1243), not in a parallel path. D3's "what would change my mind" names the right exit: a public way to compose the door would remove the slot.
  • Asks 2 to 4 are done. There's one answer-again step with two sources and one exported cap on core doWhile, the plan's answer counts toward it, and D3 rejects option (c). The take is the only other addition.
  • Correction taken. planned answers exactly once today (plan.ts:400-402), with no doWhile and no cap, so the cap is new to the shared step rather than reused from it. That was my misread, and the spec now says it correctly.

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
Comment thread specs/issues/FIX-2159/SPEC.md Outdated
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" })

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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
@jhoffner
jhoffner merged commit c8bef91 into main Oct 23, 2026
13 checks passed
@jhoffner
jhoffner deleted the spec/FIX-2159 branch October 23, 2026 23:45
jhoffner added a commit that referenced this pull request Oct 23, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants