Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
fix(orchestration): a parked filing request holds no notice; a live t…
…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
  • Loading branch information
claude committed Oct 23, 2026
commit adbcf0b364b8fbbf199eae5d034274b7a4569f1f
2 changes: 1 addition & 1 deletion .changeset/a-notice-is-taken-once.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@
"@flow-state-dev/orchestration": patch
---

A task's ending reaches the session that filed it once, on the defaults too: a `getTask({ id, wait: true })` that reads a task already ended no longer races that task's `onTaskSettled`. A notice now waits until the request that filed its task has ended (that request sends it as it ends), and `taskSettledEntry` takes a notice in one conditional write before it runs your block. A wait that finds the notice already taken returns `{ ok: true, taskId, arrivesAsNotice: true, message }` instead of the task. Task collection refs gain an optional `takeNotice(id, notice, take)`, which both built-in backings implement; a ref without it admits notices as before (FIX-2123).
A task's ending reaches the session that filed it once, on the defaults too: a `getTask({ id, wait: true })` that reads a task already ended no longer races that task's `onTaskSettled`. A notice now waits while the request that filed its task is running (not while it is parked on a person or a wait), and that request sends it as it parks or ends. `taskSettledEntry` takes a notice in one conditional write before it runs your block, and a copy never takes a notice from a request that hasn't ended. A wait that finds the notice taken returns `{ ok: true, taskId, arrivesAsNotice: true, message }` instead of the task. Task collection refs gain an optional `takeNotice(id, notice, take)`, which both built-in backings implement; a ref without it admits notices as before. A filing's `metadata` can no longer carry notice records (FIX-2123).
6 changes: 6 additions & 0 deletions .changeset/request-waits-running.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
"@flow-state-dev/core": patch
"@flow-state-dev/engine": patch
---

`RequestWaits` gains an optional `running(requestIds)`: whether each request of the running session is running its own work now (`in_progress`), as opposed to parked (`suspended`) or ended. The engine's request host implements it (FIX-2123).
9 changes: 9 additions & 0 deletions packages/core/src/types/request-host.ts
Original file line number Diff line number Diff line change
Expand Up @@ -192,6 +192,15 @@ export interface RequestWaits {
* for a request that ended without reading the task.
*/
ended?(requestIds: readonly string[]): Promise<Readonly<Record<string, boolean>>>;
/**
* Whether each request is running its own work now (`in_progress`): neither
* parked (`suspended`) nor ended. `false` for one parked
* on a person or a wait, for one that ended or whose process died, for a
* request of another session, and for one with no record. A board reads it
* to hold a task's notice while the request that filed the task still runs
* (FIX-2123), and not while that request is parked.
*/
running?(requestIds: readonly string[]): Promise<Readonly<Record<string, boolean>>>;
}

/**
Expand Down
16 changes: 16 additions & 0 deletions packages/engine/src/durability/wait-chain.ts
Original file line number Diff line number Diff line change
Expand Up @@ -250,10 +250,26 @@ export function createRequestWaits(inputs: {
}
}
return answers;
},
running: async (requestIds) => {
const answers: Record<string, boolean> = {};
for (const requestId of new Set(requestIds)) {
try {
const record = await inputs.readRequest(requestId);
answers[requestId] = record !== undefined && record.sessionId === inputs.sessionId && RUNNING.has(record.status);
} catch {
// A record that can't be read answers for itself only: not running, so nothing waits on it.
answers[requestId] = false;
}
}
return answers;
}
};
}

/** Request statuses of a request running its own work: started, and neither parked nor ended. */
const RUNNING: ReadonlySet<RequestRecord["status"]> = new Set(["in_progress"]);

/** Request statuses after which a request runs no more of its own work. */
const WORK_OVER: ReadonlySet<RequestRecord["status"]> = new Set(["completed", "incomplete", "failed", "aborted"]);

Expand Down
26 changes: 26 additions & 0 deletions packages/engine/test/wait-chain.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,32 @@ describe("whether a request has stopped running its own work", () => {
elsewhere: false
});
});

it("tells running apart from parked: only a request in progress in this session is running", async () => {
const elsewhereRunning = { id: "elsewhereRunning", status: "in_progress", sessionId: "s_other" };
const both = createRequestWaits({
provider: { ...provider([]), loadSuspension: async () => null as never },
deadlines: { defaultMs: 1, minMs: 1, maxMs: 1 },
userId: "u",
requestId: "r",
own: undefined,
sessionId: "s",
readRequest: async (id) => {
if (id === "unreadable") throw new Error("store unavailable");
return (id === "elsewhereRunning" ? elsewhereRunning : records[id]) as never;
}
});
expect(await both.running!(["running", "parked", "done", "died", "redriven", "gone", "elsewhereRunning", "unreadable"])).toEqual({
running: true,
parked: false,
done: false,
died: false,
redriven: false,
gone: false,
elsewhereRunning: false,
unreadable: false
});
});
});

describe("the stamp a waited dispatch leaves on its child", () => {
Expand Down
25 changes: 14 additions & 11 deletions packages/orchestration/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -507,12 +507,15 @@ the filer waited on (`getTask` with `wait`), nor a cancel the filer's own model
task tool in its turn. The block runs once per ending; if it throws, the notice stays owed and is
sent again. The entry queues on the session unless `concurrency` says otherwise.

A notice waits for the request that filed its task. While that request is still running (or
parked), the entry holds the notice back the way `defer` does (below), and the request sends it as
it ends. A wait in the filing request therefore reads the ending first. Before it runs `block`,
the entry takes the notice in one conditional write (the board's optional `takeNotice`, which both
built-in backings implement), so a wait that reads the task and the notice never both deliver the
same ending. A notice whose `block` threw stays owed, and the next copy takes it over.
A notice waits for the request that filed its task while that request is running, not while it is
parked on a person or a wait. The entry holds the notice back the way `defer` does (below), and the
request sends it as it parks or ends. A wait in the filing request therefore reads the ending
first. Before it runs `block`, the entry takes the notice in one conditional write (the board's
optional `takeNotice`, which both built-in backings implement), so a wait that reads the task and
the notice never both deliver the same ending. A notice whose `block` threw stays owed, and the
next copy takes it over; a copy that finds the notice taken by a request that hasn't ended,
running or parked, runs nothing. Holding needs a host that records which requests are running
(durable execution, `requestHost.waits.running`); anywhere else a notice is admitted at once.

**Holding a notice back.** Give `taskSettledEntry` a `defer(ctx, notice)` when the session can be
busy with something a notice must not run beside, such as a turn that is still under way. When it
Expand Down Expand Up @@ -1006,11 +1009,11 @@ See [Per-generator binding](https://flow-state.dev/docs/skills/binding) for the
until the task ends or the deadline passes, and returns the task as `getTask` always does. The
deadline is milliseconds from the call, five minutes by default, within the host's
`waitDeadlines` bounds. A task that already ended is returned at once, and your `onTaskSettled`
block isn't called for it: a task's notice waits until the request that filed it has ended, so a
wait in that request reads the ending first. If the notice is already being handled when the wait
reads the task (another request filed it, or its turn had ended), the wait returns
`{ ok: true, taskId, arrivesAsNotice: true, message }` instead of the task: the notice is how the
session hears that ending. At the deadline the task runs on and nothing is cancelled. If it ends before the
block isn't called for it: a task's notice waits while the request that filed it runs, so a wait
in that request reads the ending first. If the notice was taken by `onTaskSettled` before the wait
reads the task (the filing request was parked, or another request waits), the wait returns
`{ ok: true, taskId, arrivesAsNotice: true, message }` instead of the task, whether that notice is
still being handled or done: the notice is how the session hears that ending. At the deadline the task runs on and nothing is cancelled. If it ends before the
waiting request does, that request's next `getTask` on it returns the ending. If
the request ends without reading it, the ending goes to `onTaskSettled`, once. Waits nest: a
task's own turn may wait too. A wait is refused when it would make a chain of more than five
Expand Down
5 changes: 3 additions & 2 deletions packages/orchestration/src/tasks/collection/internal.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ import {
} from "../schema/task-status";
import { extractTaskItems } from "../items/extract-window";
import { applyEndingRecorder, endingOf, type TaskEnding, type TaskEndingRecorder } from "./ending";
import { deliveredByWait, droppedHeldNotices, recordEnding as recordNoticeOwed, releasedHeldNotices, takenNoticePatch, type TaskNotice } from "../notice/task-notice";
import { deliveredByWait, droppedHeldNotices, recordEnding as recordNoticeOwed, releasedHeldNotices, takenNoticePatch, withoutNoticeMarkers, type TaskNotice } from "../notice/task-notice";
import { assertDepsEditable, TaskFilingRefusedError } from "./filing";
import { hasStarted, lockedFields, type TaskEditField } from "./field-rules";
import { steersForAttempt, untakenSteers } from "../steers";
Expand Down Expand Up @@ -106,7 +106,8 @@ export function buildInitialTask<TInput, TOutput>(
priority: init.priority,
input: init.input,
labels: init.labels,
metadata: init.metadata,
// A filing can't forge, clear or settle a notice (BP-031).
metadata: withoutNoticeMarkers(init.metadata),
...(init.followUpOf !== undefined ? { followUpOf: init.followUpOf } : {}),
...(init.filedByTask !== undefined ? { filedByTask: init.filedByTask } : {}),
...(init.session !== undefined ? { session: init.session } : {}),
Expand Down
49 changes: 31 additions & 18 deletions packages/orchestration/src/tasks/collection/resource-backed.ts
Original file line number Diff line number Diff line change
Expand Up @@ -727,28 +727,33 @@ export async function createResourceBackedTaskCollection<TInput = unknown, TOutp
return { sessionId, ...(filing !== undefined ? { requestId: filing } : {}) };
}

/** The rows this request filed whose notice waits for it to end (FIX-2123). */
const filedHere = new Set<string>();

/**
* Note a row this request filed with itself as the filing request
* (FIX-2123), and, on the first, ask to be called as the request ends: a
* notice it turned away while it ran is sent then, past any backoff, rather
* than at the pass's next resend. Not at a park: the request hasn't ended.
* (FIX-2123), and ask to be called as the request stops running (it parks
* or ends): a notice turned away while it ran is sent then, past any
* backoff, rather than at the pass's next resend. The delivery registers
* once per request and board, so the call reads every row the request
* filed there, whichever resolution of the board filed it.
*/
function noteFiled(row: Task): void {
if (delivery === undefined || row.filer?.requestId === undefined || row.filer.requestId !== delivery.ownRequest) return;
const first = filedHere.size === 0;
filedHere.add(row.id);
if (!first) return;
delivery.hooks.whenRequestEnds?.(async () => {
for (const id of filedHere) {
await ref.refresh?.(id);
const row = lookupRow(id);
if (row === undefined || !owesUntakenNotice(row)) continue;
const sooner = resendNowPatch(row);
if (Object.keys(sooner).length > 0) await ref.patchMetadata(id, sooner);
await deliverAfter(lookupRow(id) ?? row);
const own = delivery?.ownRequest;
// A ledger that owes no notices (a plan board) has nothing to send, and
// its drain's parked rows are left untouched.
if (delivery === undefined || delivery.hooks.notices === false || own === undefined || row.filer?.requestId !== own) return;
delivery.hooks.whenRequestEnds?.(async (parked) => {
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.

if (filed.filer?.requestId !== own) continue;
await ref.refresh?.(filed.id);
const current = lookupRow(filed.id);
if (current === undefined || !owesUntakenNotice(current)) continue;
const sooner = resendNowPatch(current);
if (Object.keys(sooner).length > 0) await ref.patchMetadata(current.id, sooner);
// At a park the request still reads as running until its hooks have
// run, so a notice sent now would be turned away again: the filer's
// pass is owed shortly instead, and sends it once the park is recorded.
if (parked) await delivery.hooks.owePassAt(current, now() + NOTICE_DUE_MS);
else await deliverAfter(lookupRow(current.id) ?? current);
}
});
}
Expand Down Expand Up @@ -849,6 +854,14 @@ export async function createResourceBackedTaskCollection<TInput = unknown, TOutp
...(filed !== undefined ? { filed } : {}),
};

// A request that runs again after a park (FIX-2123) is a new resolution of
// the board: its own rows are noted again, so it sends what it held when
// it next parks or ends.
if (delivery?.ownRequest !== undefined) {
const own = listAll().find((row) => row.filer?.requestId === delivery.ownRequest);
if (own !== undefined) noteFiled(own as Task);
}

const ref: TaskCollectionRef<TInput, TOutput> = {
collectionId: options.collectionId,
...(options.partition !== undefined ? { partition: options.partition } : {}),
Expand Down
17 changes: 6 additions & 11 deletions packages/orchestration/src/tasks/helpers/wait-on-task.ts
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ import type { TaskCollectionRef } from "../collection/types";
import type { TaskClaimTicket } from "../claim-ticket";
import { resolveResourceCollection } from "../collection/resolve-resource-collection";
import { getOrCreateTaskCollection } from "../collection/get-or-create";
import { deliveredByWait, holdsAnEnding, LAPSED_SLOT_CHECK_CAP_MS, LAPSED_SLOT_CHECK_MS, noticeDelivery } from "../notice/task-notice";
import { deliveredByWait, holdsAnEnding, LAPSED_SLOT_CHECK_CAP_MS, LAPSED_SLOT_CHECK_MS, deliveredAsNotice } from "../notice/task-notice";
// The running request's own task, as the claim and the gate know it. Reached by
// path, not through the task-board barrel, which imports this module.
import { currentWorkerClaim } from "../../task-board/flow-policy-wiring";
Expand Down Expand Up @@ -507,9 +507,8 @@ async function ended(ctx: BlockContext, collection: TaskCollectionRef, taskId: s
* and the filer hears the ending a second time.
*
* @returns Whether the filer's `onTaskSettled` took the notice first
* (FIX-2123), read off the row as stored after the drop: the notice is the
* delivery while it is owed or the request that took it still runs, and the
* wait says so.
* (FIX-2123), read off the row as stored after the drop: that notice is the
* delivery, whether it is under way or done, and the wait says so.
*/
async function deliverEndedBeforeWait(ctx: BlockContext, collection: TaskCollectionRef, task: Task): Promise<boolean> {
const filer = collection.filerOf?.(task) ?? task.filer?.sessionId;
Expand All @@ -526,11 +525,7 @@ async function deliverEndedBeforeWait(ctx: BlockContext, collection: TaskCollect
return false;
}
}
const delivery = noticeDelivery(row, ctx.request.identity.id);
if (delivery === undefined) return false;
if (delivery.owed) return true;
const ended = ctx.requestHost?.waits?.ended;
return ended !== undefined && (await ended([delivery.by]))[delivery.by] !== true;
return deliveredAsNotice(row, ctx.request.identity.id);
}

/**
Expand All @@ -549,8 +544,8 @@ export function arrivesAsNoticeAnswer(task: Pick<Task, "id" | "goal" | "title">)
taskId: task.id,
arrivesAsNotice: true,
message:
`Task "${task.title ?? task.goal}" (${task.id}) has ended. Its ending is arriving as a notice, ` +
`which you'll read on its own; don't wait on this task again.`
`Task "${task.title ?? task.goal}" (${task.id}) has ended. Its ending comes to this conversation as a notice, ` +
`on its own; don't wait on this task again.`
};
}

Expand Down
44 changes: 32 additions & 12 deletions packages/orchestration/src/tasks/notice/delivery.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
* undeliverable, recorded on the row, and handed to the board's
* `onUndeliverable`. Nothing here fails the write that already committed.
*/
import { dispatchThroughSeam, onRequestEnded } from "@flow-state-dev/core/types";
import { dispatchThroughSeam, onRequestEnded, REQUEST_END_SEAM } from "@flow-state-dev/core/types";
import type { BlockContext, DispatchOutcome, SessionTarget } from "@flow-state-dev/core/types";
import type { Task } from "../schema/task";
import { clearNotice, NOTICE_DUE_MS, owedNotices, UNDELIVERABLE_PREFIX, type TaskNotice } from "./task-notice";
Expand Down Expand Up @@ -105,15 +105,25 @@ export interface DeliveryHooks {
patchMetadata: (id: string, patch: Record<string, unknown>) => Promise<void>
): Promise<void>;
/**
* Run `send` once the running request has ended (FIX-2123), on the
* engine's request-end seam: not when it parks, which isn't its end. A
* failure is logged, never thrown; what `send` didn't send stays owed for
* the filer's pass. Nothing runs on a context with no seam. Optional, so
* hooks built by hand keep compiling: without it, the pass sends instead.
* Run `send` once the running request stops running (FIX-2123), on the
* engine's request-end seam: as it ends, or as it parks, since a parked
* request holds no notice; `send` is told which (`parked`). A failure is
* logged, never thrown; what `send`
* didn't send stays owed for the filer's pass. Nothing runs on a context
* with no seam, or on a host that doesn't record which requests are
* running. Optional, so hooks built by hand keep compiling: without it,
* the pass sends instead.
*/
whenRequestEnds?(send: () => Promise<void>): void;
whenRequestEnds?(send: (parked: boolean) => Promise<void>): void;
}

/**
* The boards a request has asked to send at its stop (FIX-2123), keyed by
* its request-end seam, which every resolution in the request shares and a
* resume replaces. Weak, so a request's entry goes with it.
*/
const sendsAtStop = new WeakMap<object, Set<string>>();

/** The refusal that says the filer's session is gone: it can never be told. */
const FILER_GONE = "session-not-found";

Expand Down Expand Up @@ -171,17 +181,27 @@ export function createDelivery(
whenRequestEnds
};

function whenRequestEnds(send: () => Promise<void>): void {
function whenRequestEnds(send: (parked: boolean) => Promise<void>): void {
// Only where a notice can be held for this request: a host that records
// which requests have ended. Anywhere else nothing is held for it, and a
// which requests are running. Anywhere else nothing is held for it, and a
// hook would be owed for nothing: a context built outside a request's
// run (a test harness's) never runs its hooks, and a host's shutdown
// waits out its drain budget for every hook still owed in the process.
if (ctx.requestHost?.waits?.ended === undefined) return;
if (ctx.requestHost?.waits?.running === undefined) return;
// Once per request and board: every resolution of the board in this
// request reaches the same request-end list.
const seam = (ctx as { readonly [REQUEST_END_SEAM]?: object })[REQUEST_END_SEAM];
if (seam === undefined) return;
const boardKey = `${board.collectionId}\u0000${board.partition ?? ""}`;
const registered = sendsAtStop.get(seam) ?? new Set<string>();
if (registered.has(boardKey)) return;
registered.add(boardKey);
sendsAtStop.set(seam, registered);
// At a park too: a parked request holds no notice. The request that runs
// again after it registers anew (the board notes the rows it filed).
onRequestEnded(ctx, async (ending) => {
if (ending.status === "suspended") return;
try {
await send();
await send(ending.status === "suspended");
} catch (error) {
console.warn("[orchestration] a notice held for the request that filed its task wasn't sent as it ended: the filer's pass sends it", {
boardId: board.collectionId,
Expand Down
Loading
Loading