Skip to content

feat(workforce): a task's midway question is told to its filer (FIX-2241, part 2) - #4022

Merged
jhoffner merged 10 commits into
claude/project-thread-ymfvzjfrom
claude/project-thread-4xreie
Oct 28, 2026
Merged

jhoffner merged 10 commits into
claude/project-thread-ymfvzjfrom
claude/project-thread-4xreie

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 28, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project

Implements part 2 of the merged spec specs/issues/FIX-2241, a child of epic FIX-2070. Part 1 (orchestration's onMidwayQuestion hook) merged as #4003.

Stacked on #4020 (FIX-2239). This diff is FIX-2241's work only. When #4020 merges, this PR's base moves to main.

What changes

Someone who… Before After
filed a task that asks a question midway (askQuestion, askMidway, a coding run's marker) hears nothing; the question is only in the Inbox gets one message per question from the task's worker, in the conversation that filed it, naming the task and the question's id, so updateTask({ id, question, message }) answers it without getTask
filed a task routed to a workstream hears nothing hears it the same way, told the user answers it from their Inbox (its own answer is still refused question_is_the_users)
is in an exchange whose budget is spent n/a the question still arrives: the server's message pays no budget
  • conversationDelivery.onMidwayQuestion reads a teller off the running flow's onMessageReceived mark (messages/received-mark.ts, a leaf) and calls it; messageReceivedEntry builds the teller with its installation and flow kind, so any worker flow can send, the coder included. The mark and its readers (messageHearingOf too) moved to the leaf so the board imports no messages module: Fallow flagged the cycle a direct import made.
  • Where it lands: the filing worker the task's session names (FIX-2238's rule lands it in the filing session). A workstream's session names no filer, so a routed row's message goes to { session: row.filer.sessionId }.
  • Id q:<task>:<hold>: a replayed asking turn writes nothing new (FIX-2240's take on the row). The coder has no session board pass, so it is fast path only and the replay is the resend, as approved in the cross-spec review.
  • sendMessage(…, { exempt: true }): the server's own message takes a place one past its turn's hop without writing the chain row or the request count. The old budget block moved verbatim into payPlace.

Evidence

  • packages/workforce/test/midway-question-to-filer.test.ts (5 tests): one message naming task and question, one row under q:…, a later touch sends nothing more; two questions at perTurn: 1 both arrive (control: drop exempt, the test fails, run here); the routed text, the title, the shortening.
  • project-coordinator.test.ts: a task routed to a workstream whose lead asks midway tells the coordinator's conversation once, with the Inbox wording and no updateTask.
  • conversation-board-notices.test.ts (FIX-2131's held-question test) and coordinator-agent-delegate.test.ts now expect the told question where they expected nothing.
  • packages/shift-manager/test/devteam-chief-of-staff-tasks.test.ts: the coder's own question (marker) reaches the chief of staff's conversation once. Red with the hook removed (run here).
  • Suites: workforce 1640/1640. Shift Manager 571/572; the one failure is command.test.ts › getAssetPath(), which needs dist-client built (same as on feat(workforce): a worker can call another worker and wait for the reply (FIX-2239) #4020). Typecheck clean for workforce, shift-manager and goals; guard:control-shape, fallow:audit and fallow:new-dead-code pass locally against the base.
  • Goal goals/shift-manager/every-stop-is-one-inbox-item, j1 amended: j1:filer-hears, j1:filer-answers-own (now with no line from Alice after the filing), j1:one-item, j1b:coder-heard (desk.front's model files the coder's task), plus control no-question-message.
    • Real model (openai/gpt-6-luna) + Claude Code: PASS 3 of 3 (GOAL_LEGS=j1), before the cycle refactor; after it, j1 PASS again on the scripted harness and the control still fails its two tags.
    • no-question-message failed j1:filer-hears and j1b:coder-heard, as it must.
    • Differs from the spec's goal plan: j1:routed-told and the question-pays control are not walked in the goal. The desk Lab has no project or workstream to route to, and the walk never spends a budget. Both are pinned model-free instead (the project-coordinator test and the perTurn test above). goal.md says so. ask-tool-only was not added: every path goes through askMidway, so it would test nothing separate from no-question-message.

Docs

apps/docs/docs/workforce/messaging-workers.md (new "When a task asks a question", budget note), packages/workforce/README.md, one link in the task-board page. Written and edit-reviewed by the docs agents. Changeset: a-filer-is-told-its-tasks-question.md (workforce, minor).


🤖 Generated with Claude Code

https://claude.ai/code/session_01NczDiGpFCnt8J8YxSM1pHq

…essage (FIX-2241, part 2)

The conversation board's onMidwayQuestion sends one message per question from
the task's worker to the filer, under the id q:<task>:<question>, landing in
the filing session (or, from a workstream's session, the conversation the row
was filed from). sendMessage takes exempt: true for the server's own message,
which pays no budget. messageReceivedEntry's mark carries its installation and
flow kind, so the asking request finds its sender.

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

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

linear-code Bot commented Oct 28, 2026

Copy link
Copy Markdown

FIX-2241

@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 2:00am UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 28, 2026 2:00am UTC
flow-state-dev-ui Ignored Ignored Preview Oct 28, 2026 2:00am UTC

Request Review

@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-28T02:04:54.624526Z 2fb271e 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 jhoffner self-assigned this Oct 28, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (read-only; nothing run beyond reading the diff)

Verdict: the approach earns its scope. A hook in orchestration, one workforce sender, and a server-message exemption is about as lean as this gets. Nothing blocking. Three items worth the implementer's call, ranked.

1. midway-question.ts:79 reaches past a typed guardrail to find the sender (worth fixing here)

messageSenderOf((ctx as { readonly flow?: unknown }).flow) casts around FlowContextView. core/src/types/block.ts says this "shows up in review" and is the accepted-but-not-endorsed escape hatch. It works at runtime because the engine puts the whole FlowInstance under ctx.flow, so the tests pass. But a new production dependency on that is a quiet coupling to engine internals, and a type-only change to the context would break it with no compile error.

  • The session already knows its flow kind (ctx.session.identity). The installation is what's missing. If some existing path resolves an installation from a session/ctx (the hire and the message tool must), use that and drop the symbol mark carrying sender on the entry (ReceivedMark.sender, MessageSender, messageSenderOf, ~35 lines in message-received-entry.ts).
  • If no such path exists, keep the mark, but then read it through one named helper that owns the cast, so there's a single reviewed escape hatch instead of an inline as. It currently sits next to internalActionsOf, which is the natural home.

2. Dynamic import() hides a real cycle (conversation-board/delivery.ts:59, note for cleanup, not a blocker)

The PR is honest that a static import closes messages → board → messages. The lazy import is the only await import( in packages/workforce/src, so it's a new pattern, and it also turns a load-time failure into a first-question runtime failure (a bad path won't be caught by typecheck of the hook's behaviour). The cleaner shape is to break the cycle at its cause: sendMessage/messageReceivedEntry import the board for something small (likely a key or type). If that's a constant/type, moving it to a leaf module (BP-019 spirit) removes the cycle and the dynamic import together. Worth a follow-up issue if not done here; please don't leave it as the permanent shape without a comment pointing at the cycle's actual edge.

3. payPlace extraction is good; check the exempt hop (send-message.ts, exemptPlace)

Moving the budget block verbatim into payPlace is the right refactor while touching it, and Place reuses the {ok:false,error} shape so if (!paid.ok) return paid typechecks as a SendOutcome. Two second-path checks (BP-035) I couldn't confirm from the diff:

  • exemptPlace gives hop: turnHopOf(ctx) + 1 and writes no chain row. A filer that replies is a normal paid send at hop+1, so loops stay bounded. Please confirm with a test that an exempt message arriving at the hop limit's edge doesn't make the reply silently refuse in a way the filer's model can't explain. The current tests cover the question arriving, not the answer afterwards.
  • chain: turnChainOf(ctx) ?? newChainId(): on replay with no turn chain, a fresh chain id is minted per attempt. If anything keys on chain id for dedupe/display, a replay with the same q: id but a different chain differs. If only the message id is the dedupe key, ignore this.

Smaller notes

  • isRouted (row.target !== undefined || row.targetSessionId !== undefined) restates a routing predicate; if the orchestration package already exports one, reuse it so "routed" has one definition.
  • filerOf skips the question silently-ish (console.warn) when neither session nor row names a filer. Fine, since the Inbox stands; just confirm console.warn is the convention elsewhere in workforce/src and not ctx.emit.
  • Goal/docs/changeset look proportionate. Pinning routed-told and question-pays model-free instead of in the goal is a reasonable, disclosed deviation.

No architecture refactor is warranted beyond items 1–2; both are small and belong to this change because this PR is what introduces the cast and the dynamic import.


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

ℹ️ 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".

@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 / architecture pass (FIX-2241)

Verdict: The direction looks right — orchestration keeps the onMidwayQuestion hook and timing; workforce tells via the existing message log + onMessageReceived path instead of inventing a parallel notice channel. Reusing sendMessage with a stable q:<task>:<hold> id and exempt: true is the smallest way I see to get budget-free, idempotent server tells without forking delivery. I would not block on this shape.

What follows is where the implementation feels heavier than the product story, and what a cleaner diff might look like if you want to trim before merge.


What I’d keep

  • DeclaredDelivery.onMidwayQuestion — matches onTaskSettled / onUndeliverable; orchestration stays transport-agnostic.
  • midway-question.ts as a thin adapter — text, filer target, loop over holds; easy to read in review.
  • payPlace extraction — mechanical, but it makes the exempt branch obvious and avoids duplicating budget rollback logic.
  • Focused vitest file (midway-question-to-filer.test.ts) — good layer for log id + budget edge cases without dragging the whole goal walk in.

Where complexity crept in (and simpler options)

1. messageSenderOf + ReceivedMark.sender

Stamping installation + flowKind on the same symbol mark as hears works, but it mixes “who can hear” with “how the server sends as this flow.” Today midway question is the only consumer.

Lighter options (if you want less metadata on the entry):

  • Resolve sender from session keys you already carry on task sessions (TASK_FLOW_STATE_KEY / worker id + installation.workerFlows()[kind]) inside sendQuestionToFiler, same as messageHearingOf does for recipients in send-message.ts — if installation is reachable from BlockContext without mining ctx.flow.internal.
  • Or a one-line sendServerMessage(ctx, …) wrapper around { id, exempt: true } so exempt stays an implementation detail and call sites read as “server tell,” not “model send with a flag.”

I’m not sure session-based resolution is available everywhere midway runs; the mark may still be the pragmatic choice. Worth a quick check whether the (ctx as { flow?: unknown }).flow path is guaranteed to expose internal.actions at runtime (typed FlowContextView is config-only).

2. sendMessage public surface: exempt

Reasonable for one feature. If you expect more server-authored tells, a discriminated options shape or a dedicated internal entry point would make misuse (models passing exempt) easier to grep in review. Not required for this PR.

3. exemptPlace hop semantics

Multiple midway questions in one ask each call exemptPlace with the same turnHopOf(ctx) + 1, while paid sends bump via placeAfter(chainRow.sent.length). Probably fine for budget hints on exempt rows, but if recipient budget ever reflects hop literally, multi-question asks might look like one hop. Consider documenting as intentional or mirroring placeAfter without touching chain state.

4. Dynamic import() on every onMidwayQuestion

Cycle break is justified; micro-nit: a module-level lazy handle (const load = () => import(...)) avoids awaiting the import promise on every tell (ESM cache makes this small).

5. Goal walk j1 + harness growth

receivedFrom loading all requests with includeItems: true inside until polls will get expensive as the conversation grows. For a long-lived goal host that may be acceptable; a narrower API (filter by component / since request id) would be a cleaner assertion helper if the client supports it.

Adding j1b coder-heard + rewriting j1 so the filer answers from the automatic message (not Alice narrating the answer) is the right behavioral proof, but it materially expands an already heavy goal — the split to model-free tests in project-coordinator / midway-question-to-filer is good; I’d resist duplicating more routed/budget scenarios in both places.

6. project-coordinator.test.ts hears flag + inline askMidway

Fine for one routed FIX-2241 case; if more tests need “lead hears messages,” consider sharing the [ask] / askMidwayOnceInTurn pattern with conversation-board-harness rather than growing bespoke lead-task handlers.


Alternatives considered (and why I’d still ship this approach)

Alternative Why it’s simpler on paper Why this PR’s approach still wins
Inbox / getTask only (pre-2241) No messaging changes Spec wants filer onMessageReceived + teach updateTask without a read
Notice-style dispatchThroughSeam only No log/budget Loses message log, idempotent row, and the same turn UX as worker mail
Inline tell inside askMidway One file Violates workforce/orchestration boundary
Third-party package N/A No off-the-shelf fit for your delivery + budget + session seam

Performance (non-blocking)

Serial await sendMessage per hold extends the asking request until all filer dispatches finish — correct for consistency, worth knowing for multi-question asks. Repeated recipient resolution per hold in the same request could be memoized later; K is usually 1.


Summary

No major architectural red flags. The main simplify lever, if you want a smaller conceptual footprint, is whether MessageSender on RECEIVED_MARK is worth it vs session + installation resolution like the rest of the messages package. Everything else is polish, test-harness DRY, or goal-walk ergonomics.

Happy to approve once you’re satisfied the ctx.flow / sender path is a supported runtime contract (or you document the assumption).

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

…ark, with no import cycle (FIX-2241)

Fallow's audit flagged the board's delivery importing the messages modules,
which import the board. The mark messageReceivedEntry puts on its entry now
lives in a leaf (received-mark.ts) and carries the flow's teller; the board
reads it from the running flow.

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

@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. A smaller shape is on #4023 (draft, do not merge).

Fold 02615b277 onto a596e197a. Do not reset onto the POC. Close #4023 unmerged after this PR lands.

exemptPlace, isRouted, and filerOf each have one caller. The exempt arm is the object at the budget line. The routed check and the two-arm address stay where they are used. payPlace stays: moving that block into an else only indents it. MessageSender does not need export. Nothing outside the file names it.

The file header, the delivery import comment, messageSenderOf's comment, and the test header repeat the send. The short versions keep the replay id, the budget skip, the cycle, and the Inbox as the one stop.

Net −54 (+28/−82). The text, the id, who is told, and the budget skip are unchanged.

Passed: midway-question-to-filer 5, worker-messages 35, project-coordinator 41, coordinator-agent-delegate 5, conversation-board-notices 17. eslint on the five files, exit 0.

Red: forcing the exempt check false failed the spent-budget case. One message arrived. The second was per_request_limit.

Left as recorded: the exempt send, q:<task>:<hold>, the dynamic import, the sender mark, the routed sentence, one message per hold, the goal, and the docs.

Agent on this PR: fold that subtraction, then close the POC unmerged after this lands.

View PR

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

…ong task goal fits the question (FIX-2241)

A flow with no pass (the coder) sends on its own dispatch only, so a send
repeated under its id after the first ended between the row and the
dispatch now dispatches the untaken row again; the take keeps it once.
The task label in a midway question's text is cut to 200 characters, so a
long goal never pushes the message past its limit.

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

Copy link
Copy Markdown
Collaborator Author

On the simplification proposal (POC #4023): most of it no longer applies after c514080. MessageSender and messageSenderOf are gone, and the sender is now one teller on the mark in the leaf received-mark.ts. I'm keeping exemptPlace, isRouted and filerOf as named helpers, because each one carries a rule a reader needs (the shared hop, the routed check, the workstream fallback), and they now have the comments that explain those rules. I won't fold #4023 in; it can be closed unmerged.


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: 4488646c44

ℹ️ 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".

…(FIX-2241)

The answer tool refuses a confirm answered with a message alone
(confirm_takes_done), so the text told to the filer now names done: true
or false for a confirm.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGpFCnt8J8YxSM1pHq
@jhoffner
jhoffner added this pull request to stack #4046 October 28, 2026 12:08
@jhoffner
jhoffner merged commit 11b0ec3 into main Oct 28, 2026
18 checks passed
@jhoffner
jhoffner deleted the claude/project-thread-4xreie branch October 28, 2026 12:09
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