Skip to content

FIX-2238 follow-up: a fresh budget for a task held before it starts, and for a person's line in a finished task's session - #4021

Merged
jhoffner merged 18 commits into
mainfrom
claude/project-thread-n6abql
Oct 28, 2026
Merged

jhoffner merged 18 commits into
mainfrom
claude/project-thread-n6abql

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

The problem

Codex left two findings on #4010 shortly before it merged. Both are cases the approved FIX-2238 spec lists, and #4010 did not handle either:

  • A task held before it starts. A task filed pending and then held with updateTask kept its filing's chain. Once released, it could not send a single message if that chain was already spent. The spec says a task held before its first start counts as held from its filing, so it gets a fresh 6.
  • A person's line in a finished task's session. An answer now lands in a finished task's session, so a person can carry on the exchange there. Their line did not start a fresh budget, because markUserTurn skipped every task session. The spec asks for this case to be marked.

What this does

  • board.ts: when a hold succeeds on a row that hasn't started, freshenFiledHop rewrites the row's filed mark as a fresh chain, the same mark a held filing writes. It keeps the filer's user-line count. A hold on a row that has already started is a midway hold, and keeps its budget.
  • user-turn.ts: a person's line in a task session starts a fresh chain and counts as a user's line, but only once the task and every follow-up in that session have ended. It is still not marked as a user's turn, so standing-rule tools stay off there. standing-rules.test.ts pins that ("still not a user's turn").
    • The ledger is loaded with a dynamic import. A static import creates a module cycle that hangs answer-again-finished-tasks.test.ts at load.
  • Epic seam table (specs/epics/FIX-2070/DECISIONS.md): adds FIX-2239's queuedBehind to the message row, as Jake approved in the cross-spec review.

What's asked of you

Nothing to decide. This implements two notes the approved spec already records.

Everything else

Verification

  • Two new tests in test/worker-messages.test.ts. Each was run against the old code first and failed:
    • "starts a task held before its first start afresh when it is released" fails with helper-b>otto@2 when the fix is disabled.
    • "starts a fresh budget at a user's line in a finished task's session" fails on the old user-turn.ts (expected +0 to be 1).
  • packages/workforce: 1611 of 1612 pass. The one failure is "refuses a post's round at 50 open" (a 5s timeout), and it also fails on a clean checkout of main in this container.
  • Typecheck passes for packages/workforce.

Changeset: none. The behaviour is internal and the public API is unchanged.

History note: the branch carries a no-change merge of the already-merged #4010 branch. Its tree is main plus this diff.


Generated by Claude Code

claude added 13 commits October 27, 2026 21:15
…ageReceived (FIX-2238)

The tool is sendMessage, the entry onMessageReceived, replyTo is inReplyTo;
no alias for the old names (FIX-2070 ER-7).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiDWiB5JZRCvyAFUpe9
…elayed (FIX-2238)

onMessageReceived lands a history-only line and a client-only
workforce:received component, and hands the flow's turn the received
message (id, from, text, call, inReplyTo, budget). The relay goes: a worker
answers with sendMessage and inReplyTo, or not at all.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiDWiB5JZRCvyAFUpe9
An answer lands in its original's session; a message to the filer lands in
the filing session (new readonly filingWorkerId). Workers that hear only in
their tasks' sessions are refused by name before the row is written. The
delegate's ongoing session is born with its filer's count, and a task held
from its filing starts a fresh chain when released.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiDJDLpHhanaY6z9YCB
hireWorkforce refuses a worker flow without an onMessageReceived built by
messageReceivedEntry. The coder hears only in its tasks' sessions; the error
reporter's turn runs for a message. messageReceivedEntry and its types are
exported. Shift Manager draws workforce:received as its own item under the
sender's name, replacing the 'From X:' prefix match.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiDWiB5JZRCvyAFUpe9
Docs and READMEs describe sendMessage, onMessageReceived, the received
item (which now carries the budget left), the landing rules, the budget and
the refusals. The workers-message-each-other goal gets the spec's new legs,
controls and sweep. The epic's seam table, ER-6 and stack order follow the
cross-spec review.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiDWiB5JZRCvyAFUpe9
Resolve the FIX-2070 DECISIONS.md conflict by keeping both amendments:
the stack order and FIX-2160's addressedBy/toTask from this branch, the
FIX-2240 take-and-resend fields from main.

Review on #4010:
- send-message: one placeAfter helper for a send's place; the pre-read
  of the chain row is gone, since reserve, conditional update and
  give-back already refuse an over-budget send at no cost.
- messageReceivedProblem takes the flow and reads its internal actions
  itself, so the hire carries no copy of the flow's shape.
- runs-on-one-task goal: the roster's own tools are listDelegates and
  sendMessage.
- Goal leg 2b names sendMessage, since "wait" alone led the model to
  file a task and wait on it.

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

- freshHopMark mints the held task's chain at filing, so every request
  the task runs (a retry, a continuation after a question) counts in one
  budget instead of minting a new one each time (Codex on #4010).
- TURN_MESSAGED_STATE was read only by the relay this change removed;
  the field, its reset and the write on every send are gone (Cursor).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiDWiB5JZRCvyAFUpe9
A message queued behind a busy recipient, or heard after its sender sent
again, read its budget from its own row's hop, so it could report places
already spent. The receipt reads the chain row and reports from the larger
of the two (Codex on #4010).

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

recipientRefusal refused task_sessions_only before inReplyTo was read,
so a task-sessions worker's question could never be answered. An answer
lands in the session its original came from, so only a message by name
is refused now (Codex on #4010). sendMessageOutputSchema is no longer
exported: nothing outside the tool reads it (Fallow).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiDWiB5JZRCvyAFUpe9
… sends after a refusal

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiDWiB5JZRCvyAFUpe9
A ring that branches spends places before a later message is heard, so
the received budget can be below 6 minus its place. The leg now checks
it is at most that, never negative, and counts down along the ring.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiDWiB5JZRCvyAFUpe9
…and for a person's line in a finished task's session

Two Codex findings that landed as #4010 merged:
- A task held by updateTask before its first start is held from its
  filing: its filed mark becomes a fresh chain, as a filing held writes.
- A person's line in a finished task's session (every follow-up there
  ended too) starts a fresh budget. It is still no user's turn for the
  rule tools.

Epic seam table: FIX-2239's queuedBehind on the message row (cross-spec
review, approved).

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

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

Request Review

@linear-code

linear-code Bot commented Oct 28, 2026

Copy link
Copy Markdown

FIX-2238

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 28, 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-28T12:14:41.253046Z cccdd43 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.

Copy link
Copy Markdown
Collaborator Author

Second-look + architecture review (read-only; for the next agent to triage)

Overall: the direction is right and small. Both fixes match the FIX-2238 notes, and the tests were red first. Findings below, ranked. None blocks the intent; #1 and #2 are worth doing in this PR because they touch the lines being changed.

1. markUserTurn reads the wrong partition for a workstream's task session (correctness, likely)

user-turn.ts passes state[FILING_SESSION_STATE_KEY] to taskSessionEnded. steer.ts resolves the ledger via boardAboveOf(ctx) (board-above.ts), which falls back to ROUTED_FROM_STATE_KEY for a workstream's session (FIX-2083). A routed task session has a TASK_ID but no FILING_SESSION, so typeof partition !== "string" returns false and the user's line gets no fresh budget there, which is the bug this PR fixes elsewhere. Use boardAboveOf(ctx) for the partition. Add a test for a routed session, or say why it can't occur.

2. Duplicated "is the task's chain finished" logic (reuse)

taskSessionEnded re-implements the chain filter that sessionOpenTask in steer.ts already has. The two also differ: steer.ts uses (task.followUpOf ?? task.id) === taskId, while this PR uses task.id === taskId || task.followUpOf === taskId. They agree today only if follow-ups never chain off a follow-up. Pick one. Better: export a small taskChainOf(rows, taskId) (or sessionChainEnded) next to sessionOpenTask and have both call it.

3. The dynamic import is a layering smell, not just a workaround (architecture)

standing-rules/user-turn.ts is a low-level door step, and it now reaches into conversation-board/ledger (which pulls in board-entries, cascade, delivery and more). The await import() hides a real cycle: ledger -> ... -> user-turn. Two cleaner options, in order of preference:

  • Keep user-turn.ts ledger-free. Have markUserTurn take an isSessionEnded(ctx) predicate (or return a "needs-ended-check" result) supplied by the doors that already live above the board (agent-worker-flow.ts, coordinator-flow.ts). The .tap(markUserTurnStep) call sites then inject it. The predicate lives in conversation-board/ beside sessionOpenTask, so it can sit on Improve server runtime logs for action/block execution #2's helper.
  • Or, if the dynamic import stays, add a one-line test or lint note so nobody "tidies" it into a static import, since the failure mode is a hang at load, not a type error.

4. The hold and the fresh mark are two writes (robustness)

In patchSettings, ref.patchSettings(...) then freshenFiledHop -> patchMetadata. The ledger doc stresses that a debt and its write land together, "nothing can strand a start between two writes". A crash or a concurrent release between them leaves a held row on the old chain, which is the original bug again, only rarer. Since patchSettings already accepts metadata, fold FILED_HOP into the same patch (after callerMetadata strips caller keys), so the check happens in one write. If metadata merge semantics make that awkward, say so in a comment. Also decide whether re-holding an already-held, never-started row should mint a new chain each time. As written it does, which is harmless but not idempotent.

5. patch.held === true as the trigger (minor, verify)

The test holds via status: "held" through updateTask, so confirm that path reaches patchSettings with held: true, and not through a different method (e.g. a status transition) that skips this branch. The test passing suggests yes. A short comment naming the mapping would save the next reader a trace.

6. Scope and hygiene

  • Epic seam-table edit (FIX-2070/DECISIONS.md): unrelated to the two behaviour fixes. Fine as approved, but it is better in its own commit or PR so a revert of one doesn't take the other.
  • 13 commits and a no-change merge of FIX-2238: workers hear a message on onMessageReceived, sent with sendMessage #4010's branch, and mergeable_state is dirty. Merge or rebase main and re-run CI before review.
  • BP-035 second-paths not covered by tests: the off state (a started row held midway keeps its budget) and a task session with a still-open follow-up (no fresh budget). Both are in the code, neither is pinned. The second is the exact condition every(isTerminalStatus) exists for, and a test would fail if someone loosened it to some or to the root task only.
  • BP-003: the PR notes one unrelated failing test that also fails on main. Fine, but link the existing issue if there is one.

What I'd leave alone

No broader refactor of the hop/budget modules is warranted here. #2 and #3 are the only architecture changes this diff earns.


Generated by Claude Code

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

Code Snob — already tight. No POC.

Head 0232b15f6. I read packages/workforce/src/conversation-board/board.ts (keepFiledHopInChain, freshenFiledHop, patchSettings), packages/workforce/src/standing-rules/user-turn.ts, packages/workforce/src/messages/hop.ts (freshHopMark, heldFromFiling, startTurnAtHop), the two new tests in packages/workforce/test/worker-messages.test.ts and the filed-held test beside them, and the message-row cell in specs/epics/FIX-2070/DECISIONS.md. I compared steer.ts (sessionOpenTask), board-above.ts, and task-entry.ts (sessionTaskOf).

  • freshenFiledHop is the one write: a fresh chain, the filer's line count kept. Inlining it into patchSettings moves those lines. freshHopMark(ctx, mark.lines) drops the spread and adds a parameter; the filing sites want the session's current lines. The call-site comment repeats the helper. Cutting it shortens the comment. The helper comment is why a started row and a row with no mark return.
  • markUserTurn writes either the user-turn flag or an empty patch. A ternary repeats typeof taskId === "string" and saves the let. taskSessionEnded is the list, the filter, and every. Inlining it drops the name and keeps the dynamic import: a static import of the ledger hangs answer-again-finished-tasks.test.ts at load. sessionOpenTask treats a missing row as finished and reads boardAboveOf, which also takes routedFrom. This check requires a row on filingSessionId. (followUpOf ?? id) === taskId skips a root whose followUpOf is set.
  • The two tests are the two cases. The filed-held test also pins hop 0 and the chain minted at filing. A shared tail drops that or takes a flag. File, hold, assign, release is this case; file-already-held is the other.
  • The seam cell adds queuedBehind. That clause is the record.

Left as recorded: a hold before the first start rewrites the filed mark; a person's line in a finished task session starts a fresh chain and is still not a user's turn; the ledger import stays dynamic.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@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 / approach review

Verdict: The follow-up is appropriately small (~100 lines, two edge cases from FIX-2238). I would not call the overall direction over-engineered — freshenFiledHop and the finished-session hop reset are localized fixes with good integration tests. There are still a few places a cleaner shape would reduce duplication and future drift without changing behavior.

What looks right

  • Hold-before-start → fresh chain: Wiring freshenFiledHop off patchSettings when patch.held === true matches how updateTask({ status: "held" }) maps in orchestration (held: true), and parallels filing-time heldFromFiling ? freshHopMark : turnHopMark. The test that holds, reassigns, releases, and asserts @1 hops + distinct chains is strong evidence.
  • Finished task session, user line: Keeping USER_TURN_STATE off (still task input / no rule tools) while calling startTurnAtHop with an empty mark is the right split — consistent with standing-rules.test.ts (“not a user’s turn”) but fixes budget for post-completion chatter (FIX-2238).
  • Open-task hot path: steerOrTalk still routes open-chain messages to steer; markUserTurn only runs when sessionOpenTask is undefined, so in-progress task work is not regressed on the busiest path.

Where complexity crept in (and simpler alternatives)

  1. Duplicate ledger scan on the finished-chain respond path
    steerOrTalk already calls sessionOpenTask() → full ledger.list() + chain filter. When the chain is closed, the same request then hits markUserTurn → taskSessionEnded() → second conversationLedgerAt + list() + filter (inverted predicate).
    Cleaner: Share one helper with steer.ts (e.g. chainRows(ledger, rootTaskId) / chainAllTerminal) or pass the outcome of sessionOpenTask === undefined into the user-turn door so hop reset does not re-resolve the ledger. Same semantics, half the work on the path this PR cares about.

  2. Hop-mark policy in three places
    Filing (heldFromFiling → freshHopMark), hold-via-update (freshenFiledHop), and hop.ts docs. The bodies are almost the same (“fresh chain, keep lines”).
    Cleaner: One exported helper in messages/hop.ts (e.g. filedHopMarkWhenHeldFromFiling(ctx, priorMark?)) used at add + patchSettings, so hold-at-filing and hold-before-start cannot diverge.

  3. Dynamic import in markUserTurn
    Understandable for cycle avoidance, but it pushes async + module boundary into standing-rules for every call where taskId is set (partition missing still bails before import; open-chain calls are rare on this path because of steerOrTalk).
    Cleaner (larger change, optional): Set a session flag when the task chain fully settles (or reuse an existing settlement hook) so markUserTurn stays sync and does not reach into the ledger. I’m not insisting on this in this PR — flagging as the architectural alternative if hop/session rules keep growing.

  4. Hold-time vs release-time freshen
    Running freshenFiledHop on hold (not on held: false / release) is defensible — the mark is fixed before the row runs. Minor nit: repeated held: true on an already-held unstarted row would mint a new chain again; if that happens in the wild, consider freshen only on transition into held or when the mark is not already a held-from-filing shape.

  5. Scope
    The FIX-2070/DECISIONS.md queuedBehind sentence looks unrelated to this follow-up; worth splitting to keep review/merge narrative tight (soft preference, not a functional concern).

Chain membership

taskSessionEnded uses id === taskId || followUpOf === taskId, aligned with sessionOpenTask’s (followUpOf ?? id) === taskId for the flat follow-up pattern the suite uses (follow-ups point at the root task id). If nested followUpOf chains ever ship without normalization, both steer and this check would need the same transitive closure — same class of issue, not introduced only here.

Tests

Integration coverage in worker-messages.test.ts is the right tier. Optional: a small unit test on markUserTurn with mocked ledger / partition for the “all terminal → fresh chain, no USER_TURN” branch (would catch regressions without booting the harness).


Summary: Ship-worthy behavior; I’d merge after considering (1) shared chain/terminal helper with steer.ts and (2) centralizing filed-hop mark policy in hop.ts. Neither is a blocker if you want this follow-up landed quickly — they’re the main simplification levers if you touch this area again.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/epics/FIX-2070/DECISIONS.md Resolved
…uter does

markUserTurn now asks steer.ts whether the session's task chain has
finished (sessionTaskChainEnded, over sessionOpenTask), so a line counts
as a fresh budget exactly when it no longer steers: the same board
(boardAboveOf) and the same chain predicate. Still false with no board.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiDWiB5JZRCvyAFUpe9
Outcome, input, legs 1 to 4 and the controls now describe FIX-2238:
sendMessage and onMessageReceived, landing rules, the budget, the
coder's refusal, the round-robin coordinator and the hire check. The
verdict log records 3 passing runs of legs 1 to 5, the one ring run
that stopped short, and each control's FAIL.

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

Copy link
Copy Markdown
Collaborator Author

FIX-2238 goal verdict (goals/shift-manager/workers-message-each-other/, real model: workers on openai/gpt-5.4-mini, the Shift Coordinator on anthropic/claude-haiku-5-5)

Controls first. Every control failed on the assertion it targets:

Control Failed on
relay-back 1:no-relay
no-wake 1:answer-holds-codename
answer-to-conversation 2:lands-in-task-session
ongoing-at-0 3:ring-stops-at-6
no-hop-cap 3:ring-stops-at-6
pay-first 3:refused-pays-nothing
fresh-hop-on-task 3b:counts-on
no-roster-check 4:bobs-worker-refused
refuse-at-receive 4:coder-refused
no-turn-back 4:round-robin-heard
no-hire-check 4:hire-refuses
memory-log 5:lists-every-message (0 of 3 listed after the restart)

These ran on 5d7ca952b and bfbae4c08 (#4010's heads).

Then PASS: legs 1 to 5 passed in 3 runs. One run was on bfbae4c08 with this PR's changes not yet committed; two were on 570849be4.

One more run on 570849be4 failed 3:ring-stops-at-6. The ring stopped after 3 messages with no budget refusal: a hand-off the model didn't make. The ring stopped at 6 in 5 of 6 full runs this session.

A finding for FIX-2160's leg 6, which ran alongside. It failed 6:lands-in-task-session in 1 of 3 runs on 570849be4: the message's turn started before the task's turn ended. That is handed on separately; it isn't this PR's.

The verdict row and the goal's updated text for sendMessage are in d9d39a5.


Generated by Claude Code

…-n6abql

# Conflicts:
#	goals/shift-manager/workers-message-each-other/goal.md
#	specs/epics/FIX-2070/DECISIONS.md
@jhoffner
jhoffner merged commit 30e2f82 into main Oct 28, 2026
13 checks passed
@jhoffner
jhoffner deleted the claude/project-thread-n6abql branch October 28, 2026 12:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants