Repository navigation
spec(epic): dispatchTask, one tool for handing work to another worker (FIX-1870) - #3109
Conversation
… (FIX-1870) Five documents, an evolution record and six figures under specs/epics/FIX-1870/. Closure issue FIX-1887 filed and blocked by every child. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
|
@codex review |
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. |
Second look + architecture pass (spec PR, read-only review)I checked the spec's premises against 1. The FIX-1875 → FIX-1872 gap leaves two fences, and ER-10 forbids that (PLAN "Coordination seams")PLAN says FIX-1875 retires the coordinator's Simpler shape: move the coordinator 2. D2 says the ledger is "just a fence". On
|
|
Architect: Layer-1 coherence on #3109. D1 holds. D2 forks from a merged decision and the spec never says so. 1. D2 reverses FIX-1816 D3 (merged in #2900) without naming it.
2. ER-8 and ER-6 can't both hold under D2. ER-8 ("nothing changed but names") and the kill line only cover the three reruns (FIX-1816/1817/1820). D2 changes coordinator delivery from post to row, so each delegate now runs a task session. The named controls are FIX-1791 and FIX-1840, but the closure's "names-only" proof doesn't apply to them. Say what a legitimate diff there is. 3. Smaller issues.
Checked and fine.
|
Architect · coherence check on the epic-specThe direction matches the Orchestration Primitives project-spec (#3102). Two things in it still read as building in two directions, and both are about D2 / ER-5. 1. D2 reverses a merged decision that EVOLUTION.md doesn't list. FIX-1816 D3 (merged in #2900, aligned in #2905) kept a coordinator's post as a post. Its "Locks in" line says: "Two answer-once checks stay: the post's ledger token and the row's claim ticket. Each serves one kind, and no third is added." D2 and ER-5 remove that ledger token. D2's "Because" cites FIX-1815 D2 (one fence, never built), but FIX-1816 D3 is the later and more specific call, and it chose two. D2 may still be right. D3 kept the post because of what the person sees, which is each delegate's own line rather than one folded reply. ER-6 ("one answer per delegate per post per round") looks like it keeps that. If so, D2 changes only the fence and not what the person sees. That's an amendment, and it should be written down as one:
2. A third delivery marker isn't counted. FIX-1794 (#2935, merged Oct 9) shipped the conversation board's notice markers (
Otherwise FIX-1887 could pass while two fences still ship, or fail on something no child owns. Small point: FIX-1786 (where the task envelope, FSD Architect (coherence watch). |
There was a problem hiding this comment.
The redraft is the right simplification: canceling the envelope draft (FIX-1871/1874) and building on wait-for-response.ts plus row endings is cleaner than inventing reply/settle modes. D1 (one dispatchTask + wait), D2 (claim ticket only), and D3 (vocabulary) hang together, and the kill line (regression goals change beyond names) is a strong falsifier.
Where the approach is about as simple as it gets
- Keeping
dispatcher()/ FIX-1312 as flow transport (ER-12) avoids a second public hand-off path. wait: trueshould be a thin façade over existing ask machinery;wait: falseshould reuse notice/onTaskSettledpaths rather than new transport.- The FIX-1815 pivot is documented honestly in
EVOLUTION.md; the five-team table is high-signal.
Where complexity is mostly process, not product
- Three implementation children plus closure is defensible for reviewability, but PLAN’s FIX-1875 → FIX-1872 seam intentionally runs two fences until 1872 lands. That’s the main “went further than one PR” cost; consider merging 1872 into 1875 if FIX-1791 green can be held without the interim ledger (optional, not required).
- FIX-1876 as a separate issue is reasonable; the spec already names the collapse trigger if renames land early.
Nits to tighten before or in child specs (see inline)
onTimeout: "continue"is called out as the only new behaviour, which sits awkwardly next to ER-8 / “names only” and closure anti-game. Either elevate it in SPEC + ER-3 + DOCS, or drop it from this epic.- D2 row cost is named as the D2 flip condition but FIX-1887 is behavioral-only; child specs should add a concrete everyone×rounds×delegates scenario with storage/latency thresholds (ER-14), since the ledger’s bounded post window does not automatically transfer to partitioned conversation rows.
- ER-2 (
addTasknever starts work now) requires removing conversation-boardwakeon assignee present inboard.tstoday — worth one explicit acceptance line in FIX-1875’s issue spec so implementers don’t ship the tool without the CRUD split.
No changes requested on direction; approving the epic spec.
Sent by Cursor Automation: Review For Best Approach
| carries its intent; FIX-1872 closes it in favour of itself. | ||
| - **No separate wait depth.** Depth is the task chain limit, `MAX_TASK_DEPTH`. | ||
| - **`onTimeout: "continue"` is the only new behaviour, and it is a caller choice.** The row runs on, | ||
| as an unwaited dispatch would; its ending reaches the filer through `onTaskSettled`. |
There was a problem hiding this comment.
This reads as scope beyond a rename epic: ER-8 and the closure anti-game both stress parity, yet this bullet is the only place that admits net-new caller behavior. onTimeout does not appear in packages/orchestration on main today.
Suggestion (pick one): (a) promote continue into SPEC goal / ER-3 and the DOCS draft with an explicit regression or goal leg; (b) defer it to a follow-up issue; or (c) drop it here so FIX-1870 stays strictly “names + fence consolidation.”
| |---|---| | ||
| | **Instead of** | Keeping FIX-1791's delivery ledger (`packages/workforce/src/delivery-ledger.ts`) beside the claim ticket, or a lighter row-less path for group threads | | ||
| | **Because** | Two mechanisms that both decide "answered once" disagree at the edges. FIX-1815 decided on one fence ([its D2](../FIX-1815/DECISIONS.md#d2)) and never built it. A row-less path keeps a second fence alive, because something still has to refuse the duplicate answer | | ||
| | **Locks in** | A coordinator on the everyone policy, with rounds, files one row per delegate per post. One answer per delegate per post per round, and the routing record, keep working. FIX-1875's spec measures the row cost; if it's unacceptable, that comes up here, not to a local fix | |
There was a problem hiding this comment.
Good that row cost is the D2 flip. Closure (FIX-1887) as written only reruns behavioral goals + export sweep — it won’t catch everyone-policy storage blow-up.
Worth requiring FIX-1875 or FIX-1872’s issue spec to carry one bounded scenario (delegates × rounds × posts) and pass/fail thresholds, so ER-14 isn’t only a human escalation.
| |---|---| | ||
| | **Instead of** | Ask (`addTask({ waitForResponse })`) and assign as two kinds of hand-off, with the coordinator's `handOff` beside them · or the first draft: a dispatch envelope carrying a reply mode and a settle mode (FIX-1871, FIX-1874) | | ||
| | **Because** | An ask is an ordinary task row the caller waits on (`packages/orchestration/src/tasks/helpers/wait-for-response.ts`). Every way a result comes back (ask resume, `onTaskSettled`, the split wake) already comes from a row ending and runs through the board's notice code. The recipient does the same work either way; only the caller differs. So no new transport is needed | | ||
| | **Locks in** | `addTask`, `assignTask` and the other task tools are board CRUD and never start work now. `dispatcher()` stays transport for flow code; a fire-and-forget with no row is a `dispatcher()` call, not a model tool. Every rule ask carries today moves to `wait` unchanged ([ER-3](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)) | |
There was a problem hiding this comment.
Implementers will need a deliberate step: on conversation boards, guarded addTask still wakes when an assignee is present (packages/workforce/src/conversation-board/board.ts). ER-2 is false until that wake moves behind dispatchTask.
Suggest FIX-1875’s issue spec lists “strip start-now from addTask/assignTask on boards where ER-2 applies” as an explicit deliverable beside adding the tool.
|
|
||
| | Seam | Between | Rule | | ||
| |---|---|---| | ||
| | The coordinator's delivery | FIX-1875 and FIX-1872 | FIX-1875 retires the `handOff` tool, so the judgment turn delivers through `dispatchTask` rows while policy routing still runs on the ledger. FIX-1791's check must stay green across that gap; FIX-1872 closes it | |
There was a problem hiding this comment.
This seam is the epic’s main complexity tax: retiring coordinator handOff while the ledger may still fence routing until FIX-1872 merges.
The PLAN already says FIX-1791 must stay green — consider one hard rule in FIX-1875’s spec: either (1) don’t merge 1875 until 1872 is ready, or (2) judgment turn uses dispatchTask rows and a documented interim ledger bridge. Without that, two-fence drift is easy during implementation.
| | [FIX-1887](https://linear.app/fixpoint-labs/issue/FIX-1887) · closure · **required** | The QA plan and its run on one `main` commit: the three reruns, the surface sweep, every child's own check | Proves the whole ([ER-15](BUSINESS-RULES.md#the-closure)) | Backlog · blocked by FIX-1875, FIX-1872, FIX-1876 | | ||
|
|
||
| Three issues and a closure. [FIX-1871](https://linear.app/fixpoint-labs/issue/FIX-1871) and | ||
| [FIX-1874](https://linear.app/fixpoint-labs/issue/FIX-1874), the first draft's envelope and |
There was a problem hiding this comment.
The “whether three is really two” paragraph is useful honesty. If reviewability is the only reason for FIX-1876, the collapse trigger could be stated as a default preference (fold vocabulary into whichever PR last touches task-tools-capability.ts / coordinator docs) rather than a third mandatory child — optional simplification, not a blocker.
| > Your turn pauses until the task ends, then carries on with the task's output as the tool's | ||
| > result. Nothing holds a request open while it waits, so a server restart loses nothing. A wait | ||
| > has a time limit, five minutes unless you set one between 30 seconds and an hour. When it runs | ||
| > out, the task is cancelled, unless you asked to keep it running. A worker you're waiting on |
There was a problem hiding this comment.
“Unless you asked to keep it running” implies onTimeout: "continue" from DECISIONS. Published docs will teach behavior the FIX-1816/1820 reruns won’t exercise if closure stays names-only.
Align this sentence with whatever you decide on the DECISIONS bullet (promote to tested behavior vs defer).
| |---|---|---|---| | ||
| | ER-1 | A worker starts work on another worker now with one tool, `dispatchTask`: a new row or a reference, a worker, and an optional `wait`. With `wait`, its turn parks until the row ends and resumes with the row's output, or an error naming how it ended. Without it, the ending arrives through `onTaskSettled` | FIX-1875 ([D1](DECISIONS.md#d1)) | The closure's reruns | | ||
| | ER-2 | `addTask`, `assignTask` and the other task tools record work and an owner; the board decides when it runs. Only `dispatchTask` starts work now | FIX-1875 | FIX-1875's goal check | | ||
| | ER-3 | Every rule ask carries today holds under `wait`, unchanged: a waited-on row can't park on a question · the waiting turn owns the row's lifetime, and only its filer hears a cancel · `onTimeout: "cancel"` is the default · bounds 30 seconds to an hour, default 5 minutes · one row per call, one wait per step · `wait` only where the host can resume a parked turn and a sweeper bounds every wait · depth is `MAX_TASK_DEPTH` · the description says to wait only when the next step needs the result | FIX-1875 | The FIX-1816 and FIX-1820 reruns | |
There was a problem hiding this comment.
ER-3 documents onTimeout: "cancel" as default but not continue. If continue ships in FIX-1875, ER-3 should list it here (and in FIX-1875’s goal check) so ER-8’s “unchanged” claim stays coherent.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2f0d80e460
ℹ️ 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".
|
|
||
| | # | Rule | Owner | Checked at | | ||
| |---|---|---|---| | ||
| | ER-1 | A worker starts work on another worker now with one tool, `dispatchTask`: a new row or a reference, a worker, and an optional `wait`. With `wait`, its turn parks until the row ends and resumes with the row's output, or an error naming how it ended. Without it, the ending arrives through `onTaskSettled` | FIX-1875 ([D1](DECISIONS.md#d1)) | The closure's reruns | |
There was a problem hiding this comment.
Preserve target-session routing in dispatchTask
When one lead owns multiple project workstreams, the existing coordinator must call handOff({ worker, target }) to select the correct existing session (packages/workforce/test/project-coordinator.test.ts:507-525); targeted workstream delegates are explicitly rejected by the ordinary task path as “takes posts, not tasks” (packages/workforce/src/delegates/worker-delegates.ts:270-287). ER-1 defines the replacement using only a row/reference and worker, while PLAN.md:20 retires handOff, so the specified API cannot express this production route. Preserve target/existing-session addressing in dispatchTask, or retain handOff until parity exists.
Useful? React with 👍 / 👎.
| |---|---|---|---| | ||
| | ER-1 | A worker starts work on another worker now with one tool, `dispatchTask`: a new row or a reference, a worker, and an optional `wait`. With `wait`, its turn parks until the row ends and resumes with the row's output, or an error naming how it ended. Without it, the ending arrives through `onTaskSettled` | FIX-1875 ([D1](DECISIONS.md#d1)) | The closure's reruns | | ||
| | ER-2 | `addTask`, `assignTask` and the other task tools record work and an owner; the board decides when it runs. Only `dispatchTask` starts work now | FIX-1875 | FIX-1875's goal check | | ||
| | ER-3 | Every rule ask carries today holds under `wait`, unchanged: a waited-on row can't park on a question · the waiting turn owns the row's lifetime, and only its filer hears a cancel · `onTimeout: "cancel"` is the default · bounds 30 seconds to an hour, default 5 minutes · one row per call, one wait per step · `wait` only where the host can resume a parked turn and a sweeper bounds every wait · depth is `MAX_TASK_DEPTH` · the description says to wait only when the next step needs the result | FIX-1875 | The FIX-1816 and FIX-1820 reruns | |
There was a problem hiding this comment.
Resolve the contradictory wait-depth contract
For a worker already executing a task, the shipped addTaskAndWait path refuses before filing (packages/orchestration/src/tasks/helpers/wait-for-response.ts:159-190), and the predecessor contract deliberately fixes wait depth at one (specs/epics/FIX-1815/DECISIONS.md:162-168). Saying both that this rule remains unchanged and that depth is MAX_TASK_DEPTH instead permits nested waits through the task-chain limit. Either retain the task-turn prohibition or treat nested waits as a behavior change with explicit safety and regression coverage.
Useful? React with 👍 / 👎.
| | How we verify | | | ||
| |---|---| | ||
| | **Goal check** | The closure issue, [FIX-1887](https://linear.app/fixpoint-labs/issue/FIX-1887), on one `main` commit after every other child merges ([ER-15](BUSINESS-RULES.md#the-closure)) | | ||
| | **Signal** | `goals/hand-offs/ask-survives-a-restart/` (FIX-1816), `goals/coordinators/task-session-stays-open/` (FIX-1817) and `goals/hand-offs/survives-a-restart-and-runs-once/` (FIX-1820) each get the result they got before, with workers that use only `dispatchTask`. The public exports, tool lists and docs carry no `waitForResponse` or `timeoutMs` on `addTask`, no coordinator `handOff` tool, no `post-to-mailbox`, and no delivery ledger | |
There was a problem hiding this comment.
Add coordinator regressions to the closure signal
The closure signal runs only the FIX-1816, FIX-1817, and FIX-1820 checks plus a surface sweep, none of which proves D2's migrated coordinator behavior: one answer per delegate/post/round, round closure, and onward routing. Although BUSINESS-RULES.md:18 names the FIX-1791 and FIX-1840 coordinator checks, they are not required by this pass criterion, so removing the ledger could duplicate or drop coordinator answers while the stated epic goal still passes. Require those coordinator checks in FIX-1887's assembled-set run.
Useful? React with 👍 / 👎.
| - **`onTimeout: "continue"` is the only new behaviour, and it is a caller choice.** The row runs on, | ||
| as an unwaited dispatch would; its ending reaches the filer through `onTaskSettled`. |
There was a problem hiding this comment.
Prove the new continue-on-timeout behavior
When a wait times out, the shipped contract always cancels its row (specs/issues/FIX-1816/BUSINESS-RULES.md:54), whereas this option lets the work continue and later sends an onTaskSettled notice. That is observable new behavior despite the spec's names-only/no-behavior-change success condition, and no listed closure control exercises it. Either remove the mode or widen the goal and add explicit proof for timeout, later settlement, and restart behavior.
Useful? React with 👍 / 👎.
| | "Giving another worker work" above, replacing the ask section and the `waitForResponse` / `timeoutMs` table rows | FIX-1875, with the tool | This document; option table in FIX-1875's `DOCS.md` | | ||
| | `background-work.md` "Waiting for the answer" rewritten to point at the section above | FIX-1875 | Its `DOCS.md` | | ||
| | `coordinators.md` and `chief-of-staff.md`: the `handOff` tool replaced by `dispatchTask` | FIX-1875 | Its `DOCS.md` | | ||
| | `coordinators.md`: one answer per delegate per post, fenced by the task row | FIX-1872 | Its `DOCS.md` | | ||
| | The glossary rows above; every remaining use of "ask" or "hand-off" for delivering work, across `apps/docs` | FIX-1876 | This document, then its `DOCS.md` | |
There was a problem hiding this comment.
Include package READMEs in documentation ownership
The ownership table covers only docs-site pages, but packages/orchestration/README.md:721-749 still teaches waitForResponse/timeoutMs, while packages/workforce/README.md:1595-1690 teaches coordinator handOff. Following this plan would leave installed-package readers with removed APIs, so assign both README migrations and include them in the closure sweep.
AGENTS.md reference: AGENTS.md:L210-L211
Useful? React with 👍 / 👎.
…, handOff retires with the ledger, coordinator checks in the closure - D2 names the FIX-1816 D3 amendment; Open 1 asks the owner whether a coordinator post becomes rows - coordinator handOff retirement moves from FIX-1875 into FIX-1872, one change with the ledger (ER-10) - closure adds the three coordinator checks, a scripted rename-map diff, package READMEs in the sweep - wait depth stays one and a timeout cancels, as shipped; onTimeout continue dropped - notice marker and openWorkstream clarified; FIX-1840 check reference corrected Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Open 1, raised from the architect's D2-vs-FIX-1816-D3 comment, is answered by the owner (2026-10-11): anything that needs a confirmed answer is a task through |


addTask({ waitForResponse: true }). A flag turns a board tool into a delivery tooldispatchTask({ …, wait: true }). The park, the resume and the limits do not changedispatchTaskwithoutwait.addTaskandassignTaskonly record workGoal: a worker that needs another worker to do something has one tool that starts the work now and can wait for the result. Today it has to pick from four tools that overlap.
The reruns show that the behaviour did not change, for a waiter or a coordinator. The sweep (exports, tool lists, docs, package READMEs) shows that the old tools are gone. The closure issue FIX-1887 runs this check. Today's
mainmust fail the sweep: SPEC.md.The box holds one tool and one fence. The names change. The behaviour does not.
Why now. FIX-1815 closed on 2026-10-11. Three passing goal checks now pin ask and assign, so a behaviour change shows as a failing check. FIX-1637's docs and FIX-1796's term cleanup wait for this vocabulary.
The set: FIX-1875 adds
dispatchTask. FIX-1872 moves coordinator delivery to rows and removeshandOffand the delivery ledger in one change. FIX-1876 does the docs and the names. FIX-1887 is the closure. As of 2026-10-11: all four are in Backlog. The spec has the snapshot and the links to live state.The specs can run in parallel. The implementations cannot, because each one gives the next a surface that must stop changing.
Each rule has one owner.
Sign off
One tool,
dispatchTask, with an optionalwait· D1The decision comes from the recipient: it does the same work for an ask and an assign. If wrong: the model waits when it should not, and turns park for no reason.
Every coordinator delivery is a row; the claim ticket is the only fence · D2
The decision comes from two fences that disagree. It amends a merged decision, FIX-1816 D3, and waits on Open 1. If wrong: a coordinator post answered twice, or each delegate's own line folded into one.
Open 1 · When a coordinator passes your message on to its delegates, does that become a task, or stay a message?
FIX-1816 (merged) kept a post a post, so each delegate's answer shows as its own line. Recommendation: make it a task, if FIX-1872's spec first shows each delegate's own line, rounds and routing survive as rows. If not: D2 narrows to task endings and the ledger stays for posts. The project-spec's Open 2 (#3102) is the same question. This PR should not merge until it is answered: DECISIONS.md → Open.
D3, the vocabulary, is the owner's decision from 2026-10-11. What would change my mind on D1: one regression check that cannot stay the same. That is the kill line. Reasoning: DECISIONS.md.
Reviewers · look here
handOffnow retires in FIX-1872, with the ledger, so no build ships two fences. The closure now reruns the three coordinator checks (FIX-1791, FIX-1794, FIX-1610) as well.onTimeout: "continue"was dropped as new behaviour.post-to-mailboxis already gone (FIX-1792,617aeabb5). FIX-1875 has nothing to remove there. The sweep still checks it.Not here: the approach of one issue. Those are the spec PRs.
Spec · Decisions · Rules · Plan · Docs · Evolution
· Linear FIX-1870 · Project: Orchestration Primitives · merges after human approval and required checks
How to review this — an epic-spec, not an implementation plan
This is an epic-spec: the shared objective and cross-cutting decisions for a set of
issues, in a retained document set. It is not any one issue's implementation design.
In scope to challenge:
SPEC.md— is this body of work worth doing, and is thegoal the real need at full size, or a smaller one the set could meet while the need stays
unmet? Would the closure issue's check fail if the goal were not met?
That question can only be asked here.
DECISIONS.md— shared surface, naming, sequencing, contracts.BUSINESS-RULES.mdwith no owner, or two.DOCS.md; missing or misleadingpredecessor treatment in conditional
EVOLUTION.md.Out of scope — owned by the individual issue specs:
poc/show shape and scoping, not shippable implementation. Directional evidence, experimental
isolation and absence of secrets/generated dependencies remain in scope.
Feedback in the second list is routed to the issue it concerns as an implementer note, not
folded in here.
Required repository checks, approvals and review-thread policy still govern merge.
Optional comments are triaged, not a reason to grind to zero or restart the design review.
🤖 Generated with Claude Code