Skip to content

fix(orchestration): a task's ending reaches its filer once, on the defaults too (FIX-2123) - #3733

Merged
jhoffner merged 9 commits into
mainfrom
fix/FIX-2123
Oct 23, 2026
Merged

jhoffner merged 9 commits into
mainfrom
fix/FIX-2123

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

The problem

A session that files a task should hear the task's ending once. When the session waits on the task with getTask({ id, wait: true }) after it has already ended, it can hear the ending twice: once as the wait's answer, and once from onTaskSettled, which wakes a second turn on the same ending. FIX-2112 closed this only for flows whose onTaskSettled waits behind the turn that filed the task, which is how Workforce sets things up. A flow on the defaults (taskSettledEntry({ block })) still heard it twice every time. In Workforce, a second reply that waited on a task while that task's notice turn was already running heard it twice as well.

What this does

  • A task's notice waits for the request that filed it. The row now records which request filed it. While that request is still running or parked, its notices are held back, the way taskSettledEntry's defer holds one back. When the request ends, it sends whatever is still owed right away. A wait inside the filing request therefore always reads the ending before the notice runs, and drops it.
  • A notice is taken before it runs. Before the flow's block runs, onTaskSettled takes the notice in one conditional write. A wait's drop and a take can't both go through. If the block throws, the notice stays owed, and the next copy takes it over once the failed request has ended.
  • A wait that finds the notice already taken says so. It returns { ok: true, taskId, arrivesAsNotice: true, message }. The message names the task and says its ending is arriving as a notice, so the model doesn't take it as "no result" and wait again.

What's asked of you

Nothing here is yours to decide. One call shapes behaviour you can see: who backs off when a notice and a wait race. The epic's engineering manager made that call against the epic objective (every ending reaches its filer once, on the defaults). It is under Engineering calls below.

Parts worth reviewing closely

  • packages/orchestration/src/tasks/notice/task-settled-entry.ts: the admit order. defer, then "the filing request still runs", then the take. Taking over a take whose request has ended is how a failed block's notice gets resent.
  • packages/orchestration/src/tasks/notice/task-notice.ts: the take is a record beside the marker (noticeTaken:<attempt>:<ending>), like the resend and deferral records. It stays after the marker clears, so a wait can still see that the request delivering the ending is running. Workforce's handling clears the marker before the turn it wakes, so this matters there.
  • packages/orchestration/src/tasks/collection/resource-backed.ts → filerFor / noteFiled: the filing request is stamped only when the filer is this session. A follow-up filed elsewhere carries no request id, because another session's request is never answered as ended.
  • packages/orchestration/src/tasks/helpers/wait-on-task.ts → deliverEndedBeforeWait: re-reads the committed row after a drop that a take beat.

Links

Linear FIX-2123 (bug, epic FIX-2056). Found in review 5627158643 on #3697 (FIX-2112). Builds on FIX-2113's deferredAt / resendNowPatch. Draft; a human merges.

How to review this

How to review this. This is a bug fix on the direct route: there is no spec and no spec PR, because the hard part was the diagnosis and it happened in code. This PR is the only gate, so unlike a spec-backed change, the approach is in scope: nothing here was signed off upstream.

Most valuable here: the diagnosis chain. Does the repro actually reproduce the reported failure? Is the named cause the real one? Does the fix address that cause rather than the symptom, and does the regression test fail without the fix? Then the second path (the legacy shape, the null boundary, the concurrent case, the cancel path).

In scope to challenge: where the guard was placed, any behaviour change a user could notice, and whether this should have been a spec'd feature instead of a fix.

Engineering calls

The notice steps aside while the turn that filed the task runs (decided by the epic EM)

The issue asked for a claim alone: admission marks the marker taken, so exactly one of the wait's drop and the admission goes through. Measured on main with FIX-2112's test minus noticeAfterTurn (3 of 3 runs), the notice is admitted 2–3 ms before the wait reads the row. The fast path sends it the moment the ending is written. So a claim alone lets the admission win, and the filer still hears the ending twice. The options were:

  1. claim only, keeping the docs condition;
  2. claim, plus the notice steps aside while the filing request runs, plus the wait says "arriving as a notice" when it loses;
  3. the wait always yields to a taken notice.

The EM picked 2: it is the only option that keeps the epic's promise on the defaults, and it can be undone. Constraints carried out:

  • The filing request id is stamped server-side from ctx.request.identity.id (BP-031).
  • A row with no request id (stored before this change, or a follow-up filed from another session) is admitted as before.
  • The deferral reuses FIX-2113's deferredNoticePatch (deferredAt) and resendNowPatch.
  • Sent right away when the filing turn ends: yes, through the engine's request-end seam (onRequestEnded), not the backoff. It doesn't fire at a park, because a parked request hasn't ended. A request that parks and later ends gets its held notices from the pass's next resend (at most 5 minutes). The hook isn't registered again after a resume.

Consequences worth knowing

  • A notice now waits out a parked filing request. A turn parked on a wait for task A, or on a human approval, holds the notices of the other tasks it filed until it ends. Their age doesn't run while they are held (deferredAt). Treating "parked" as ended would let a resumed turn's wait on B race B's notice again.
  • On a host with no record of ended requests (non-durable; requestHost.waits.ended is absent), nothing is held back and a take is always replaceable. That is the old behaviour. Waits can't be made on such a host anyway.
  • A wait after the notice has fully run (its request ended) still returns the ending, as today. That is a read after the hearing, not a second delivery.
  • takeNotice and DeliveryHooks.whenRequestEnds are optional, so a hand-written ref or hooks object keeps compiling and behaves as before.
  • A held marker (a lapsed wait's, FIX-2082) is never taken. Today such a marker is never sent anyway.

Smaller calls

  • Where the take lives: a record beside the marker, not a field in it. It survives the clear, which Workforce needs (above), and a cleared marker can't come back.
  • The "arriving as a notice" answer omits the task's status and output. Repeating them would be the second hearing.
  • Path 2 is tested twice: in orchestration (a flow with hold/defer set as Workforce does) on the in-memory and SQLite stores, and in Workforce itself (conversation-board-wait.test.ts).
  • Changeset: patch, for consumers of the published @flow-state-dev/orchestration: the new answer shape, the new optional ref method, and the notice timing.
Everything else

Red, then green

Red is the new tests run against main's packages/orchestration/src, with only the tests and fixture from this PR applied:

  • notice-claim.test.ts, defaults path, in-memory and SQLite: expected [ { boardId: 'waits', …(4) } ] to deeply equal []. onTaskSettled's block ran beside the wait.
  • notice-claim.test.ts, notice already running, in-memory and SQLite: expected '{"ok":true,…"status":"completed","output":"already done"}' to contain 'arriving as a notice'.
  • Workforce conversation-board-wait.test.ts (FIX-2123): the same assertion, through the real getTask.
  • notice-take.test.ts, state-backed and resource-backed: tasks.takeNotice is not a function. With the method present and deliveredByWait ignoring the take (a mutation), "a take first leaves the wait's drop nothing to drop" fails on both backings.
  • notice-defer.test.ts, failed block: expected undefined to deeply equal Any<String> (nothing took the notice).
  • "A turn that never waits hears its ending once, as the turn ends" is green on main. It guards against this change holding the notice too long. Its red was produced by disabling the request-end send: not within 1500ms on both stores.

Green: all of the above pass. FIX-2112's test with noticeAfterTurn: true stays green.

Checks

  • pnpm typecheck (includes the side-chain vocabulary sweep): pass.
  • pnpm lint: pass.
  • pnpm fallow:ci: pass.
  • node scripts/check-retired-terms.mjs: pass.
  • Tests: orchestration 2099/2099, workforce 1566/1566, patterns 213/213, integration-tests 154 (+3 skipped), harness-manager 265/265.
  • The closure's task-surface sweep (goals/workforce-coordination/runs-on-one-task/sweep.mjs from fix/FIX-2087, run on this tree): PASS.
  • Child goal goals/task-board/waits-on-a-task-it-filed legs a and c (model-free): PASS. "A piece that ended before its wait was read by it; 0 onTaskSettled requests delivering it."
  • The closure's real-model j1 was not run. This bug came from review, not the closure.

Docs

  • packages/orchestration/README.md: the "waits behind the turn" condition is gone; the hold-until-the-filing-request-ends rule, the take and the arrivesAsNotice answer are added.
  • apps/docs/docs/orchestration/task-board.md: written through docs-writer then docs-editor (separate commit on this branch).

Generated by Claude Code


Note

Medium Risk
Changes notice admission, getTask wait answers, and request-end delivery in durable orchestration; regressions would double-notify or drop endings, though coverage is broad.

Overview
Fixes FIX-2123 so a session hears each task ending once, including default flows where onTaskSettled no longer has to queue behind the filing turn.

Notice timing: Filed tasks record the filing request id (server-side). While that request is in_progress, its task notices are deferred (like defer); when it ends, delivery hooks flush held notices immediately via whenRequestEnds / onRequestEnded (not on park). RequestWaits.running in core/engine powers that distinction.

Single winner between wait and notice: onTaskSettled takes a notice in a conditional takeNotice write before the block runs; a concurrent getTask wait either drops the marker or sees a taken notice and returns { ok: true, taskId, arrivesAsNotice: true, message } instead of the task body. Filing metadata can no longer smuggle notice/take markers.

Docs, README, and integration tests (orchestration + Workforce) cover the new races and failure/retry paths.

Reviewed by Cursor Bugbot for commit 69831f2. Configure here.

…faults too (FIX-2123)

A notice was admitted by a read, not a claim, so a filer's wait and its
onTaskSettled could both deliver one ending. Now:

- A row records the request that filed it (server-side, from the engine's
  request identity, only in the filer's own session). Its notice is turned
  away, as `defer` turns one away, while that request still runs, and the
  request sends it as it ends (the request-end seam), past any backoff. A
  wait in the filing request reads the ending first and drops the notice.
- taskSettledEntry takes a notice in one conditional write before it runs
  the block (`takeNotice`, both backings). A wait's drop and a take can't
  both go through. A block that throws leaves the notice owed, and the next
  copy takes it over once the failed request has ended.
- A wait that finds the notice taken (still owed, or its request still
  running) answers `{ ok, taskId, arrivesAsNotice, message }`, naming the
  task, instead of the ending.

Tests: the defaults path and Workforce `hold` path, red first, on the
in-memory and SQLite stores, and on both backings for the take; a turn that
never waits still hears its ending once, as it ends; a failed block's notice
is taken over.

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

linear-code Bot commented Oct 23, 2026

Copy link
Copy Markdown

FIX-2123

@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 4:42pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 23, 2026 4:42pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 23, 2026 4:42pm UTC

Request Review

@cursor

cursor Bot commented Oct 23, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 0a2ca801-b265-4f8e-85cd-e6be2e41e2ed)

Update "Waiting on a task" and "Hearing how a task ended": a wait on an
already-ended task takes the ending whatever the entry's options, a wait
while the notice is being handled gets arrivesAsNotice, and a notice is
held until the request that filed the task has ended.

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

cursor Bot commented Oct 23, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: e140a22d-1d06-42d8-aed3-9dd00806d416)

…eld (FIX-2123)

The send at the filing request's end registered a request-end hook at
every filing on a board that delivers. A context built outside a
request's run (testBlock's) never runs its hooks, and the engine keeps
owed hooks process-wide: every later host shutdown in the process then
waited out its 10 s drain budget. On CI's shared module cache that made
wait-on-task.test.ts time out test by test.

The hook is registered only where a notice can be held for the request:
a host that records which requests have ended (`requestHost.waits.ended`).
Anywhere else nothing is held, so nothing needs sending at its end.

Regression test: a row filed under testBlock, then a host's dispose
finishes in under 2 s (it took the 10 s budget before).

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

cursor Bot commented Oct 23, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 4b456f12-894c-4dd2-a594-5554e65c4f15)

Copy link
Copy Markdown
Collaborator Author

CI's wait-on-task.test.ts timeouts are fixed in 0501d15.

Cause: the send at the filing request's end registered a request-end hook at every filing on a board that delivers. A context built outside a request's run never runs its hooks (testBlock's, used in immutable-assignee.test.ts). The engine keeps owed hooks in one process-wide map, and a host's dispose() waits up to its 10 s drain budget for them (drainRequestEnds). On the shared module cache, once such a file had run in a worker, every later dispose() in that worker took 10 s, so each wait-on-task test hit its 5 s timeout.

Fix: the hook is registered only on a host that records which requests have ended (requestHost.waits.ended). That is the only place a notice can be held for the filing request. Without it, nothing is held, so nothing needs sending at the request's end.

Regression test: notice-claim.test.ts, "a row filed by a block run outside a request". It files under testBlock, then checks that a host's dispose finishes in under 2 s. With the guard removed it times out at 5 s, the same failure CI showed.

Checks:

  • pnpm --filter @flow-state-dev/orchestration exec vitest run test/tasks/wait-on-task.test.ts: pass.
  • Full orchestration suite, three runs: 2100/2100 each.
  • Workforce: 1566/1566.
  • pnpm typecheck, pnpm lint, pnpm fallow:ci: pass.

The docs commit 7e5b3c9 (task-board.md, written through docs-writer then docs-editor) is on the branch too.


Generated by Claude Code

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

Stand-in review (Bugbot is out of usage) at 0501d1522. I traced the five areas below in code and ran the new tests plus two mutations in a throwaway worktree.

🔴 A filing request parked on a person or on getTask holds the notices of every other task it filed, with no upper bound

The question: should a notice wait out a park, or only a running turn?

The trace:

  • task-settled-entry.ts turns a notice away while !(await hasEnded(ctx, filing)).
  • hasEnded reads requestHost.waits.ended. In engine/src/durability/wait-chain.ts, ended is true only for WORK_OVER (completed / incomplete / failed / aborted), or for interrupted when nothing will drive the request again. A suspended request reads not ended.
  • So for the whole of a park, each copy the pass sends is deferred (deferredNoticePatch), and the notice's age is reset each time.

Take a turn that files B and then asks a person for approval. Before this PR, B's notice woke its own turn during the park: the park releases the session's concurrency key, and the resume takes it back (execution-and-errors.md, FIX-2062). Now B's ending is silent until the person answers. If the approval has no expiry, that can be never. The same holds for a turn parked on getTask for A: B's ending waits on A. A person who is waiting to hear B before they approve is stuck. The PR names this under Consequences, but it is a behaviour change users will see, and it wasn't put to a product decision. (I couldn't find a written FIX-2077 rule about notices during a person-park. FIX-2077 is the request-end seam and waitingOn. Today's behaviour is still what users get, and this PR takes it away.)

The reason given ("treating parked as ended would let a resumed turn's wait on B race B's notice again") is now covered by the take this PR adds. If B's notice is admitted during the park and taken, a resumed wait on B finds the take. deliveredByWait leaves the marker, and noticeDelivery makes the wait answer arrivesAsNotice. That is one hearing. Recommendation: hold only while the filing request is actually running. That needs waits to tell suspended apart from running. Today ended folds the two together, so this is an engine-side addition. The other option is to keep the hold and get explicit sign-off that a parked turn silences its other tasks. What being wrong costs: a conversation goes quiet on finished work for as long as a person takes to answer.

🟡 The request-end send is lost across a park, so a parked-then-ended filing request delivers late

createDelivery.whenRequestEnds registers on onRequestEnded, and the hook returns early on status === "suspended". Request-end hooks run on the suspension path (request-end-hooks.ts), so the hook is used up at the park. The resumed run's collection starts with an empty filedHere and never registers again. Held notices then go out at the pass's next resend. After a long park their backoff has grown to the cap (NOTICE_RESEND_CAP_MS = 5 min). The PR says so, but it is cheap to fix: on resume, re-register for the rows whose filer.requestId === ownRequest, or call resendNowPatch on them when the resumed request ends.

🟡 "Only once" while the first taker still runs is not covered by any test

In the worktree I removed this line from task-settled-entry.ts:

if (taker !== undefined && taker !== own && !(await hasEnded(ctx, taker))) return { owed: false };

The full orchestration suite (2100/2100) still passed, and so did Workforce's conversation-board-{wait,notices,notice-bounds}. Without that line, a second copy calls takeNotice with replacing: taker and takes a notice from a request that is still delivering it, so the block runs twice. That can happen when a notice turn parks on a person and the pass resends. The failed-block test in notice-defer.test.ts runs on a host where the first taker has already ended, so it covers only the takeover branch. A test where the taker is still running (or parked) and a resend arrives would pin this line.

🟣 Not blocking

  • A taken notice whose taker is parked ages out. A copy that finds a running taker returns { owed: false } without deferredNoticePatch. If the taker is parked longer than maxDebtAgeMs (24 h by default), pass.ts settles the notice undeliverable while it is still being delivered. A rare edge, and better than before this PR, when the block would have run again.
  • A crashed filing request. ended reads interrupted as ended unless it will be driven again, so the hold lifts. The request-end hook never fires, so the notice goes out at the next resend (≤ 5 min after the sweep marks the request interrupted). Not lost.
  • BP-031: holds. filer.requestId and take.by both come from ctx.request.identity.id. buildInitialTask never reads filer from init. One nit: createTask's init.metadata passes noticeTaken:* keys through unfiltered, as it already does noticeOwed:*. A planted take suppresses the wait's drop, but the takeover path still delivers the notice once, so this is not an auth problem. Consider stripping notice-record prefixes from init metadata.

Verified, no finding

  • Take vs drop on both backings. noticeReadByWaitWrite and noticeTakeWrite are both decided inside patchRef / patchOne on the row as stored. A drop needs a sendable marker and no taker; a take needs a sendable marker and a taker of none / self / replacing. Exactly one goes through. "Neither" only happens when the taker's block fails, and the takeover covers that. Two concurrent takeovers: the second one's replacing no longer matches, so it is refused.
  • Failed block's takeover. Re-sent by the pass (owesUntakenNotice rightly leaves taken markers out of the request-end send), and taken over once. The test passes.
  • Mutation that bites. In deliverEndedBeforeWait, replacing the ended([delivery.by]) check with return false fails Workforce's FIX-2123 test. Orchestration's notice-claim.test.ts still passes, so the marker-cleared-before-the-turn path is pinned only in Workforce.
  • notice-claim, notice-defer and notice-take tests pass (18/18).

Generated by Claude Code

…aker is never replaced (FIX-2123)

Review 5630613272 on #3733:

- A notice is held only while the request that filed its task is running,
  not while it is parked on a person or a wait. Core's RequestWaits gains an
  optional `running(requestIds)`, which the engine implements (in_progress,
  this session); `ended` folded suspended and running together. The request
  sends what it held as it parks too: the record still reads in_progress
  while its hooks run, so the filer's pass is owed shortly instead.
- A request that runs again after its park notes the rows it filed when it
  resolves the board, so it sends what it held as it next parks or ends.
  Registered once per request and board; never on a ledger that owes no
  notices (a plan board).
- A wait on a task whose notice another request took answers
  arrivesAsNotice whether that notice is under way or done.
- A copy that finds the notice taken by a request that hasn't ended,
  running or parked, runs nothing and records itself as turned away, so the
  notice doesn't age out while it is delivered.
- A filing's metadata can't carry notice records.

Tests: a filer parked on a person hears its task during the park, and its
resumed wait answers arrivesAsNotice; a request that runs again after its
park sends the held notice as it ends; a second copy beside a running or
parked taker runs nothing (red when the live-taker line goes); engine
`running` tells running from parked.

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

cursor Bot commented Oct 23, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 47199593-933f-4e70-9817-818770e5ee3c)

Copy link
Copy Markdown
Collaborator Author

Replies to review 5630613272, finding by finding. The fixes are in adbcf0b.

🔴 A parked filing request holds its other tasks' notices. Fixed, per the EM's call: a notice is held only while the filing request is running.

  • Engine signal: core's RequestWaits gains an optional running(requestIds), documented on the type. The engine implements it: in_progress, this session. false for parked, ended, another session, no record, or a record that can't be read. It has an engine test, and a changeset for core and engine.
  • Send at a park: the request now sends what it held when it parks, not only when it ends. Its record still reads in_progress while its request-end hooks run, so at a park it owes the filer's pass a wake NOTICE_DUE_MS out instead of dispatching right away.
  • Tests (notice-claim.test.ts, in-memory and SQLite):
    • A filing turn files B and parks on a person. B's notice is heard during the park.
    • After approval, the resumed turn's wait on B answers "arrivesAsNotice":true, not the ending.
    • Red when the hold goes back to "not ended": the notice is never heard during the park.
  • Behaviour change: deliveredAsNotice now answers arrivesAsNotice whenever another request took the ending's notice, whether that notice is still being handled or done. The ended(taker) check is gone, so a resumed wait never hears the ending a second time.

🟡 The request-end send is lost across a park. Fixed by re-registering on resume.

  • A resolution of the board in a request that filed rows on it now notes them. The send is registered once per request and board, keyed by the request-end seam, which a resume replaces.
  • When it runs, the send reads every row that request filed on that board.
  • It is never registered on a ledger that owes no notices: plan boards have nothing to send. Touching a drain's handed-over rows at its park broke worker-plans-its-steps.
  • Test: a request runs again after its park, the task ends while it runs, and the request ends. The notice is heard within 1 s of the end, not at the resend. Red without the re-registration (the notice arrives about 2 s later).

🟡 "Only once" while the first taker still runs.

  • Tests (notice-defer.test.ts, durable host): a second copy arrives while the first copy's request is (a) still running its block, or (b) parked on a person in its block. Each time it answers { owed: false } and the block runs once.
  • With the taker !== own && !hasEnded(taker) line removed, both fail: (a) the second copy takes the notice over and blocks behind the gate, timing out; (b) the block runs twice.
  • Under the new rule: this line keeps ended, not running. A parked notice turn still holds its take and is never taken over mid-delivery. Only a taker that has ended (its block failed, or its process died) is taken over.

🟣 A taken notice is marked undeliverable mid-delivery. Fixed. A copy that finds a live taker now records itself as turned away (deferredNoticePatch), so the notice's age restarts with each resend and it doesn't age out while it is being delivered. Pinned by the same notice-defer tests.

🟣 A crashed filer's notices arrive late. Left as is. The hold lifts once the request reads as interrupted, and the next resend (at most 5 minutes later) delivers it, so nothing is lost.

🟣 noticeTaken:* passes through init.metadata. Fixed: buildInitialTask now strips every notice record (withoutNoticeMarkers) from a filing's metadata. Tested in notice-take.test.ts.

Checks:

  • orchestration: 2108/2108 (three full runs)
  • workforce: 1566/1566
  • engine: 4011 (+8 skipped)
  • pnpm typecheck, pnpm lint, pnpm fallow:ci: pass

The task-board.md wording for the new rule is being redone through docs-writer, then docs-editor, and will land as its own commit on this branch.


Generated by Claude Code

…etired ask word (FIX-2123)

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

cursor Bot commented Oct 23, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 5868ae48-96c8-46fb-a7aa-bbdfa0fd8310)

…AsNotice after the notice starts (FIX-2123)

Correct "Hearing how a task ended" and "Waiting on a task": a notice waits
only while the filing request is running and goes out during a park; any
wait after an onTaskSettled request for the ending has started gets
arrivesAsNotice, whether that request is still running or finished.

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

cursor Bot commented Oct 23, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 86738494-372b-483c-a88e-6d91d4dba26a)

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

Stand-in review, round 2 (Bugbot is out of usage), at dc20268c8. I reviewed 0501d1522..dc20268c8, skimmed the whole PR against main, and ran mutations in a throwaway worktree, since removed. On the unmodified head: orchestration 2108/2108, workforce 1566/1566, engine wait-chain.test.ts 15/15.

🔴 The park-time send opens a lost-resume window. The notices === false guard hides it on plan boards only.

The question: should a request do board I/O in its request-end hook while it parks?

The worker didn't confirm why worker-plans-its-steps broke. I tracked it down. The guard is a mask, not a fix.

  • What the hook does at a park. Before this round, whenRequestEnds returned straight away on suspended. Now it runs at the park: adoptUnknownRows (a full collection.list()), then a refresh (an updateState round trip) for every row the request filed, then owePassAt.
  • Where that lands in the engine. runAction.ts runs request-end hooks before the record is written suspended, and after the wait gate has been stored. A task-bound wait whose task ends inside that window gets resumed through payOwedResumes → resumeWaitGate. resumeWaitGate sees a pending gate on a request that still reads in_progress, so it refuses with already-resolved ("…not parked"). That refusal isn't the retryable busy. payOwedResumes treats already-resolved as done and clears the resumeOwed marker, so nothing resumes the turn until the wait's deadline.
  • Evidence on the plan board. I removed the guard and logged the hook. It never patched a row (owesUntakenNotice was false for all three steps). Its only effect was the time it took. With the guard removed and the hook made a no-op, the FIX-2082 D2 tests pass. Add a 100 ms sleep to that no-op hook and they fail the same way the worker saw (s-draft stays pending, no answer turn). A 5 ms sleep passes.
  • Evidence on a delegation board, where the guard doesn't apply. I put the guard back and added a sleep only on the parked branch of the hook. conversation-board-wait.test.ts › "a task session's turn that waits on a task it filed (FIX-2082) › waits, reads the task as it ended, and answers its own task from it" fails at 30 ms: it times out at 10 s. With no sleep it passes in 476 ms. The suite passes today only because in-memory I/O is fast. On SQLite or Postgres, a list plus one round trip per filed row can take 30 ms or more.
  • What users see. A turn that files tasks on a conversation board and then waits on one of them can miss that task's ending, if it lands while the turn is parking. The wait then resumes at its deadline (five minutes by default) with the task as it stood, not its ending.

Recommendation: fix the window in the engine and drop the guard. A pending gate whose request still reads in_progress is "not parked yet", so resumeWaitGate should refuse it as busy (retryable), the way it already does for an interrupted request with no gate on its log. The alternative is to re-check task-bound waits after suspended is recorded, as resumeIfChildEnded does for request-bound ones. If neither fits this PR, at least make the park branch do no board I/O: owe a single pass wake. Note that the park send isn't pinned by any test (next finding), so trimming it costs no coverage.

What would change my mind: if already-resolved on a pending gate in an in_progress request is caught somewhere I missed, this drops to 🟡. The 30 ms reproduction above says it isn't caught.

What being wrong costs: waits in production stall for their whole deadline, intermittently and depending on store latency. That is hard to debug from the outside.

🟡 The park-time owePassAt is not pinned by a test

When I replaced if (parked) await delivery.hooks.owePassAt(current, now() + NOTICE_DUE_MS) with a no-op, notice-claim and notice-defer still passed (16/16). That includes "a filing request parked on a person holds nothing…", which presumably gets its notice from the pass's ordinary resend. Fix 2 ("a request that parks sends what it held") is a claim with no red state. Either pin it (for example, assert the notice is heard within roughly NOTICE_DUE_MS + ε of the park, with the resend backoff above that) or drop it as part of resolving the 🔴.

🟡 task-board.md now gets a lapsed wait wrong

The new text says: "If it ends while your request is parked on something else, or your request ends without reading it, you hear about it once, the usual way." The code doesn't do that. After a wait's deadline the row's slot is lapsed. markerFor records an ending onto it as held: true, which isn't sendable. releaseAtRequestEnd keeps the slot across a park ("an ending that lands meanwhile is held for its read after the resume"), and releaseEndedWaits releases it only on ended. So the request's next getTask after the resume returns the ending. That is exactly what the old text said ("even while your request waits on something else, your next getTask on it returns the ending"), and the README still says it. The running/parked rule applies to other tasks' notices, not to a lapsed wait's own ending. Restore the old sentence for the lapsed-wait case.

Otherwise the page matches the new behaviour and has no implementation leakage.

🟣 Not blocking

  • A host with ended but no running silently loses the hold. Both isRunning and the whenRequestEnds guard key off running. A third-party RequestWaits written against round 1 (which has ended) goes back to the pre-PR race. That is safe, because the take still makes wait and notice exclusive. The core/engine changeset could still say that implementers should add running to keep notices held.
  • A park whose record write takes longer than NOTICE_DUE_MS (2 s). The pass wakes, still reads in_progress, and turns the notice away. It then waits for the resend backoff. That's late, not lost.

Verified, no finding

  • running() in the engine is in_progress AND record.sessionId === inputs.sessionId, and false for no record, an unreadable record, parked, ended, died, re-driven, or another session. The engine test covers each of these. A crashed request reads in_progress until the sweep marks it, so the hold lasts until then, as ended did before.
  • A host without running: isRunning → false (nothing held), and whenRequestEnds doesn't register, so nothing is owed at dispose. Consistent.
  • Re-registration on resume: the sendsAtStop WeakMap is keyed by the request-end seam. createExecutionContext builds one registry per run, so a resume gets a fresh seam and registers again. Mutation: with the constructor-time noteFiled skipped, "a request that runs again after its park sends the notice it held as it ends" fails on both in-memory and SQLite. ✅
  • The hold rule: mutation to put back !hasEnded(filing) in place of isRunning(filing). "a filing request parked on a person holds nothing…" fails on both backings. ✅
  • The live-taker line keeps hasEnded, so a parked notice turn isn't taken over, and the copy now records deferredNoticePatch (round 1's 🟣 is fixed). deliveredAsNotice dropping the ended(taker) check is right, now that the take is the single source.
  • At request end the record already reads completed before the hooks run, so deliverAfter isn't turned away by the filing request's own hold.
  • buildInitialTask strips notice records via withoutNoticeMarkers, and notice-take.test.ts covers it.
  • BP-007: RequestWaits.running is documented on the type, and so are DeliveryHooks.whenRequestEnds and isRunning. Changesets: request-waits-running.md (core + engine, patch) and a-notice-is-taken-once.md (orchestration, patch) are both present.

Generated by Claude Code

…ked request held (FIX-2123)

Review 5631310696 on #3733. The request-end hook ran at a park too, doing
a list, a refresh per filed row and a pass wake. Engine hooks run before
the record is written suspended, so that time widened a window in which
a task-bound wait's resume is refused already-resolved and its
resumeOwed marker cleared: the turn stalled until its deadline. The
notices === false guard only hid it on plan boards.

Now the hook does nothing at a park: a parked request holds no notice, so
the filer's pass sends what it held at the notice's next send. The guard
is gone; worker-plans-its-steps and the FIX-2082 waits pass without it,
and still pass with 100 ms added to the hook after the park return.

Unit test: whenRequestEnds runs nothing at a park and sends once the
request ends (red without the park return); once per request and board;
nothing on a host that doesn't record running requests. The core/engine
changeset says a host with its own RequestWaits should add `running`.

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

cursor Bot commented Oct 23, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 9450d788-b25f-4989-a506-fa2587902f4a)

Copy link
Copy Markdown
Collaborator Author

Replies to review 5631310696. The fixes are in 0652a15.

🔴 Board I/O at a park. Fixed by doing no I/O at a park, per the EM's call. resumeWaitGate stays as it is; the engine race is being filed as its own bug.

  • whenRequestEnds now returns before anything else when the status is suspended. A parked request holds no notice, so the filer's pass sends whatever it held at that notice's next send.
  • The park-time owePassAt is gone, and so is the notices === false guard.
  • worker-plans-its-steps and the FIX-2082 D2 tests pass without the guard. Workforce's "a task session's turn that waits on a task it filed" passes too.
  • Using your method, I added a 100 ms sleep to the hook after the park return: conversation-board-wait and worker-plans-its-steps still pass (29/29).
  • Regression test: in delivery-after-ending.test.ts, whenRequestEnds runs nothing at suspended and sends once at completed. It fails without the park return.
  • The end-to-end variant isn't covered. There's no cheap test seam for "a board I/O delay inside the park window". A request-end hook registered by the test delays the park in the same way, so it would only re-show the engine bug, not check this code. I didn't build one.

🟡 The park-time owePassAt wasn't pinned by a test. It's removed, so there's nothing left to pin. The "parked on a person" test still passes, because the notice now comes from the pass's ordinary resend. The trade-off: a notice held while the request ran goes out at its next resend after the park. That can be later than before if its backoff has grown (at most 5 minutes). The docs say so.

🟡 task-board.md gets a lapsed wait wrong. The sentence is being corrected. After a deadline, if the task ends while the request still runs or is parked on something else, the request's next getTask returns the ending. The task's notice goes out only if the request ends without reading it. The park-wording correction goes in the same change. Both are being written through docs-writer, then docs-editor, and will land as their own commit on this branch. The README already says this.

🟣 A host with ended but no running. The core/engine changeset now says a host that supplies its own RequestWaits should add running to keep notices held.

🟣 A park whose record write takes longer than NOTICE_DUE_MS. Left as is. The notice is late, not lost: the resend backoff delivers it.

Checks:

  • orchestration: 2111/2111
  • workforce: 1566/1566
  • engine wait-chain: 15/15
  • pnpm typecheck, pnpm lint, pnpm fallow:ci: pass
  • Every Process guards script, including the vocabulary sweep and its --control run: pass

Generated by Claude Code

…sed wait's ending goes to the next getTask (FIX-2123)

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

cursor Bot commented Oct 23, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 652954d5-a8cf-405f-9e01-cbdfc2aa0d11)

@jhoffner
jhoffner marked this pull request as ready for review October 23, 2026 16:48
@jhoffner
jhoffner merged commit f740b61 into main Oct 23, 2026
21 checks passed
@jhoffner
jhoffner deleted the fix/FIX-2123 branch October 23, 2026 16:48
@cursor

cursor Bot commented Oct 23, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: a994d635-034f-4a60-a7ff-5319c144b0d5)

@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 read (FIX-2123)

I read the full diff (~1.1k lines) with parallel passes on code quality, performance, and reuse. No blocker from this review; the size is mostly tests and docs, which match the risk.

Did the approach go too far?

The bug is really three coupled races, not one:

  1. Filing turn still running — onTaskSettled must not beat the filer's getTask({ wait }) to the ending.
  2. Park vs end — holding must follow running, not “request exists,” or parked turns stall notices incorrectly.
  3. Wait drop vs notice admit — FIX-2112 drop and dispatch need a single winner under concurrent writes.

A narrower fix (Workforce-only defer, or wait-drop tweaks without defaults) would leave default boards and cross-request races. Extending RequestWaits.running + filer.requestId + conditional takeNotice is the smallest platform story that covers “defaults too,” and it reuses the existing seam (onRequestEnded, deferredNoticePatch, noticeReadByWaitWrite / patchOne). I would not chase a third-party package here; the behavior is row metadata + request lifecycle, which is already the framework’s model.

What did add surface area:

  • New metadata family (noticeTaken:*) and deliveredAsNotice / arrivesAsNotice tool shape.
  • noteFiled + whenRequestEnds flush on resource-backed boards.
  • ~500 lines of new tests (appropriate for this class of bug).

Cleaner follow-ups (optional, not merge gates)

Area Suggestion Confidence
Request-end hooks Extract shared “register on request end, skip on suspended” helper (same shape as wait-on-task / task-request) High — duplication only
noteFiled Track filed task ids per request (like lapsedByRequest) instead of listAll() on every request end Medium — perf/clarity on large boards
takeNotice decline Consider routing outcome !== "recorded" through notNow() so defer/aging matches other “not admitted” paths Medium — behavior under contention
deliveredAsNotice + lingering noticeTaken After ack, clearNotice clears owed marker but not take record; a later wait on the same terminal row may still see arrivesAsNotice. If that’s impossible by contract, a test would pin it; if repeat waits are allowed, consider clearing take on ack or requiring an owed marker in deliveredAsNotice Uncertain — needs product call
State-backed No noteFiled flush — fine if documented; only matters for custom hosts with delivery + ownRequest Low
Zod Derive arrivesAsNotice tool schema from arrivesAsNoticeAnswer Nit

Performance note

noteFiled runs inside onRequestEnded (after drains, before terminal status): adoptUnknownRows + full-board scan + per-row refresh / deliverAfter. Correct to skip on suspended; still worth watching if boards grow beyond session scale. Not a reason to block this PR.

What’s strong

  • Park vs end split in whenRequestEnds is the right latency/correctness trade.
  • Conditional take vs wait drop is the right primitive.
  • In-memory + SQLite + workforce integration tests give real evidence.

Verdict: Approach is justified for “once, on defaults too.” I’m leaving comment (not a formal approve) so the inline items below are visible; I’d be comfortable approving after the uncertain deliveredAsNotice / repeat-wait question is either tested or explicitly ruled out.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

* and leaves it to be sent again. A wait answers so, not with the ending: the
* notice is the filer's one hearing of it.
*/
export function deliveredAsNotice(row: Task, requestId: string): boolean {

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.

Possible repeat-wait edge (uncertain): deliveredAsNotice keys off noticeTaken:* via takerOf, while clearNotice only clears the owed marker. After a successful notice delivery, the take record can remain. If a new request in the filer session waits again on the same terminal row, this may still return true and surface arrivesAsNotice even though the ending was already heard.

If repeat waits on the same ending are out of contract, a short test + one-line invariant in docs would close this. If they’re allowed, consider clearing the take key on ack or requiring an active owed marker here.

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.

Real, still on main: once the notice turn clears the marker, a later request's getTask({ wait: true }) still gets arrivesAsNotice back, and no result comes with it. Filed as FIX-2181.


Generated by Claude Code

by: own,
...(taker !== undefined && taker !== own ? { replacing: taker } : {})
});
if (took.outcome !== "recorded") return { owed: false };

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.

Consistency nit: When takeNotice returns something other than recorded, admission returns { owed: false } without deferredNoticePatch. Other “not now” paths use notNow(). Under write contention, this might skip defer/aging behavior the pass expects. Worth aligning if you’ve seen flaky resend timing in tests.

if (delivery === undefined || own === undefined || row.filer?.requestId !== own) return;
delivery.hooks.whenRequestEnds?.(async () => {
await adoptUnknownRows(mirror, options.collection);
for (const filed of listAll() as Task[]) {

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 later: This hook scans listAll() on every request end for rows with filer.requestId === own. For session-sized boards that’s fine, but it’s O(board) on the request-end critical path (after drains). A per-request Set<taskId> filled at file time (same idea as lapsedByRequest in wait-on-task) would shrink the hook and avoid re-scanning unrelated rows.

whenRequestEnds
};

function whenRequestEnds(send: () => Promise<void>): void {

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.

Reuse: whenRequestEnds mirrors the onRequestEnded + skip-suspended pattern already in wait-on-task / task-request. Not wrong to duplicate once, but a tiny shared registrar would keep park-timing rationale in one place if more features register end hooks.

@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 exists, and it is comments only.

The park return, the take, and the hold while the filing request runs are each told again beside the line that does them. The test file header repeats the test names. Say each fact once. The entry header, the take-record section, and the test names already keep them.

POC (draft, does not merge): #3739 (poc/shorter-notice-once @ b74057d6c). Net −80 lines (+38/−118). Comment-stripped source matches 69831f2. notice-take and whenRequestEnds: 14 passed. eslint clean. Dropping the park return failed “runs nothing at a park” (send called on suspended).

Fold b74057d6c onto main. Do not reset onto the POC. This PR has landed (f740b61c). Close #3739 unmerged.

Left as recorded: the take beside the marker, a park holds no notice, arrivesAsNotice omits the task, the request id comes from the engine, optional takeNotice, the README, the docs page, both changesets. Tried and left: one helper for hasEnded and isRunning (the missing-host defaults are opposite).

Files: delivery.ts, task-settled-entry.ts, task-notice.ts, resource-backed.ts, wait-on-task.ts, internal.ts, task.ts, request-host.ts, task-tools-capability.ts, notice-claim.test.ts.

View PR

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

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