Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
531bf32
FIX-2429: task board changes reach open screens as board notices
claude Nov 3, 2026
96d51eb
FIX-2429: start the goal's idle windows once the views go quiet
claude Nov 3, 2026
6b0f245
FIX-2429: drop a board read that lands after watchTasks stops; review…
claude Nov 3, 2026
edf30c5
FIX-2429: drop the goal check's unused say helper
claude Nov 3, 2026
56a2872
chore(labs): mark the two lab adapters' shared LabAdapter shape as in…
claude Nov 3, 2026
547ff60
FIX-2429: useSubscription hands read an AbortSignal; Shift Manager dr…
claude Nov 3, 2026
02d4072
Merge origin/main into fix/FIX-2429-board-notices
claude Nov 3, 2026
1cdac67
FIX-2429: Teammates cards keep the spend the board read already folded
claude Nov 4, 2026
80f529b
Merge origin/main into fix/FIX-2429-board-notices
claude Nov 4, 2026
24d3b3e
shift-manager: port main's FIX-2393 registry drift into the byte copies
claude Nov 4, 2026
8b9daba
FIX-2429: every committed row write publishes a board notice, task-ch…
claude Nov 4, 2026
1eb85d6
Merge origin/main into fix/FIX-2429-board-notices
claude Nov 4, 2026
8d73ed4
fallow: ignore toolRunOpen in Shift Manager's registry copy, as #4654…
claude Nov 4, 2026
a565619
Merge remote-tracking branch 'origin/main' into fix/FIX-2429-board-no…
Copilot Nov 4, 2026
bd3c606
Merge the branch's own main merge (a5656197d) into fix/FIX-2429-board…
claude Nov 4, 2026
36f6e39
registry: say user in tool-naming's copies, as #4654 does
claude Nov 4, 2026
4453c0a
FIX-2429: one precedence rule for a Teammates row's copies: newest up…
claude Nov 4, 2026
a600d3a
FIX-2429: a Teammates row is the board read's; other copies only fill…
claude Nov 4, 2026
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
16 changes: 16 additions & 0 deletions .changeset/board-notices.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
"@flow-state-dev/orchestration": minor
"@flow-state-dev/engine": minor
"@flow-state-dev/react": minor
"@flow-state-dev/core": patch
"@flow-state-dev/contracts": patch
"@flow-state-dev/shift-manager": patch
---

A task board's change reaches every open view of the board, from whichever session or process settles the task (FIX-2429).

- **orchestration:** every change to a board built by `getOrCreateTaskCollection` also publishes a `board` change notice on the topic of the session that filed the row (`Task.filer`, else the ledger's legacy filer, else the running session), narrowed to the board's `collectionId`. A screen subscribes `topic.session(conversationId, { resource: "tasks" })` and reads again. Nothing to wire: the `task-change` item is unchanged. The board's `listTasks` action (a client's read, not the model's tool) also answers each row's `updatedAt`, so a client holding a row from two sources keeps the newer.
- **engine:** the block context carries the seam that publishes a board notice on the running request's bus, under its tenant, with the request as `origin`.
- **react:** **Breaking for a hand-built client slice:** a live `BoardList`'s `client` takes `subscribe` in place of `sessions.stream`. A client from `createClient` works as before. The list now hears a task that settles in another session or process, never wakes on a reply streaming in the session, and reads every 3 s where push can miss a change. `useSubscription` takes `client`, for an app that builds its own client, and hands `read` an `AbortSignal` that aborts when the subscription ends.
- **core / contracts:** `ChangeKind` gains `"board"`; `publishBoardChange` and `BOARD_NOTICE_SEAM` (framework-facing) in `@flow-state-dev/core/types`.
- **shift-manager:** the conversation's task panel and task cards read on board notices; they keep their 3 s timer only while a task is open, and only where push can miss a change.
11 changes: 6 additions & 5 deletions .fallowrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -136,12 +136,13 @@
"packages/shift-manager/src/components/flow-state/spend.tsx"
],

// One named export, not a whole file. Kitchen Sink's byte copy of the registry's
// tool-grouping carries `toolRunOpen`, the open-while-running rule the labs follow
// (specs/issues/FIX-2393/SPEC.md, "One step-run state"); the registry's own
// ToolGroup keeps its `defaultOpen` prop, so nothing in Kitchen Sink calls it.
// One named export, not a whole file. Kitchen Sink's and Shift Manager's byte
// copies of the registry's tool-grouping carry `toolRunOpen`, the open-while-running
// rule the labs follow (specs/issues/FIX-2393/SPEC.md, "One step-run state"); the
// registry's own ToolGroup keeps its `defaultOpen` prop, so neither app calls it.
"ignoreExports": [
{ "file": "apps/kitchen-sink/components/flow-state/tool-grouping.ts", "exports": ["toolRunOpen"] }
{ "file": "apps/kitchen-sink/components/flow-state/tool-grouping.ts", "exports": ["toolRunOpen"] },
{ "file": "packages/shift-manager/src/components/flow-state/tool-grouping.ts", "exports": ["toolRunOpen"] }
],

// Dead code fails `fallow audit` at its default severity. Complexity reports
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/docs/api/client.md
Original file line number Diff line number Diff line change
Expand Up @@ -491,7 +491,7 @@ The topics come from `topic`, which `@flow-state-dev/client` and `@flow-state-de

Each takes an optional `{ resource }` to watch one resource under the scope. A topic without one also hears changes narrowed to a resource under it. User and org topics name no id: the server fills them in from the signed-in caller, so a client can't ask for someone else's.

A notice's `kind` is `"items"`, `"request"`, `"run"`, `"state"`, `"resource"` or `"resync"`; `origin.requestId` names the request that made the change, when a request did.
A notice's `kind` is `"items"`, `"request"`, `"run"`, `"state"`, `"resource"`, `"board"` (a task on one of the session's boards changed, on a topic narrowed to the board's id) or `"resync"`; `origin.requestId` names the request that made the change, when a request did.

**On a host with push** (`serve()` from `@flow-state-dev/node`, `fsdev dev` and `fsdev serve`), the client opens one WebSocket, shared by every `subscribe` call on that client. It asks the server for each topic first, through the client's own `fetcher`, so a bearer token your fetcher adds is what proves who the socket is. A topic the caller may not read is left out, the same way a session that doesn't exist is: `onChange` never hears about it, and with `pollIntervalMs` the client asks for it again at each tick, so access given back recovers without a remount. Each connect and reconnect calls `onChange(null)` once. The server closes a socket after an hour and the client reconnects, which checks every topic again.

Expand Down
8 changes: 5 additions & 3 deletions apps/docs/docs/api/react.md
Original file line number Diff line number Diff line change
Expand Up @@ -178,18 +178,20 @@ Use `source: { response }` to consume a pre-fetched POST stream (inline streamin

### `useSubscription(topics, read, options?)`

Runs `read` again when something under `topics` changes, through the provider's client and [`fsd.subscribe`](/docs/api/client#fsdsubscribetopics-options).
Runs `read` again when something under `topics` changes, through the provider's client (or `options.client`) and [`fsd.subscribe`](/docs/api/client#fsdsubscribetopics-options).

```ts
useSubscription([topic.session(sessionId)], refresh, { pollIntervalMs: 3000 });
useSubscription([topic.session(sessionId, { resource: "tasks" })], refresh, { pollIntervalMs: 3000 });
```

| Argument | Type | Notes |
|----------|------|-------|
| `topics` | `WireTopic[]` | From `topic.session(id)`, `topic.user()`, `topic.org()`. A new array with the same topics keeps the subscription. |
| `read` | `(notice: WireNotice \| null) => unknown` | The screen's read. One runs at a time, and at most one more waits. Gets the notice that woke it, or `null` when the screen should read everything again: after a connect or a reconnect, on a timer tick, and when push starts or stops reaching every server process. It also gets `null` when several changes arrived during one read (one follow-up read covers them all). |
| `read` | `(notice: WireNotice \| null, signal: AbortSignal) => unknown` | The screen's read. One runs at a time, and at most one more waits. Gets the notice that woke it, or `null` when the screen should read everything again: after a connect or a reconnect, on a timer tick, and when push starts or stops reaching every server process. It also gets `null` when several changes arrived during one read (one follow-up read covers them all). |
| `read`'s `signal` | `AbortSignal` | Aborted when the subscription ends: the screen unmounts, or its topics or options change. A read that awaits checks `signal.aborted` before it sets state or starts more work, since a read already running when the screen goes away still finishes. |
| `options.pollIntervalMs` | `number` | Read at this pace wherever push can miss a change. Omitted, no timer. |
| `options.enabled` | `boolean` | `false` subscribes nothing. Default `true`. |
| `options.client` | `Pick<Client, "subscribe">` | Your own client, when you build one with its own `fetcher`, so the socket signs in the same way. Pass a stable reference. Default: the provider's client. |

Returns nothing. It doesn't read on mount.

Expand Down
10 changes: 8 additions & 2 deletions apps/docs/docs/client/react.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,12 +170,18 @@ const refresh = useCallback(
[sessionId],
);

useSubscription([topic.session(sessionId)], refresh, { pollIntervalMs: 3000 });
useSubscription(
[topic.session(sessionId, { resource: "tasks" }), topic.session(sessionId, { resource: "plan" })],
refresh,
{ pollIntervalMs: 3000 },
);
```

The topics are narrowed to the two boards `listTasks_tasks` returns (the conversation's tasks and its planning worker's steps), so a reply streaming in the session doesn't wake the read; a task that settles in another session still does (see [Task boards](/guides/realtime#task-boards)).

On the Node host the read runs as soon as the change is saved, over a WebSocket; on a host with no push it runs every `pollIntervalMs`. A burst of changes runs it once more after the read in flight finishes, not once per change. The read gets the notice that woke it (`{ topic, kind, origin? }`), or `null` when the screen should read everything again: after a connect or a reconnect, on a timer tick, and when push starts or stops reaching every server process. Act on `kind` when the screen only cares about some changes, and read everything on `null`. Leave `pollIntervalMs` out for no timer. `enabled: false` subscribes nothing.

The hook doesn't read on mount; keep the first read where the screen already makes it. It uses the provider's client, so the provider's `fetcher` signs the socket in. See [`fsd.subscribe`](/docs/api/client#fsdsubscribetopics-options) for which topics a caller hears.
The hook doesn't read on mount; keep the first read where the screen already makes it. It uses the provider's client, so the provider's `fetcher` signs the socket in. An app that builds its own client passes it as `client` instead. See [`fsd.subscribe`](/docs/api/client#fsdsubscribetopics-options) for which topics a caller hears.

### Background work

Expand Down
14 changes: 14 additions & 0 deletions apps/docs/docs/orchestration/task-substrate.md
Original file line number Diff line number Diff line change
Expand Up @@ -545,6 +545,20 @@ The `task` snapshot is the post-mutation row minus the fields the substrate keep

UIs stay in sync off that stream rather than by polling. The `<TaskPlan />` component and the DevTool subscribe to `task-change` items, filter by `collectionId`, and rebuild the board's state from them. You don't wire any of it up: every collection `getOrCreateTaskCollection` hands you emits these items itself.

### Board notices

The item lands on the stream of the session that made the change. A task often settles somewhere else: in its own task session, or on another process. So every change also publishes a board notice. It goes on the topic of the session that filed the row (the session that filed the row, or the running session when the row names no filer), narrowed to the board's `collectionId`, with kind `board`. It carries no rows. A screen subscribes `topic.session(conversationId, { resource: "tasks" })` with `client.subscribe` or `useSubscription`, and reads the board again when one arrives:

```ts
useSubscription(
[topic.session(conversationId, { resource: "tasks" }), topic.session(conversationId, { resource: "plan" })],
refresh, // your board read, run again on each notice
{ pollIntervalMs: 3000 },
);
```

Subscribe each board your read returns. Workforce's `listTasks_tasks` read merges the conversation board with its planning worker's steps, so its screens subscribe `tasks` and `plan`. Because the topic is narrowed, a reply streaming in the conversation never wakes the screen. `useSession`'s live stream doesn't react to board notices. As with any notice, `pollIntervalMs` is the fallback wherever push can't reach (see [Keeping a screen current](/guides/realtime#task-boards)).

## Related pages

- [Task board](./task-board.md) — the concurrent drain built on a TaskCollection.
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/docs/workforce/coordinators.md
Original file line number Diff line number Diff line change
Expand Up @@ -475,7 +475,7 @@ It hears when a task completes, with what came back; when it fails for good, wit

| Action | What it does |
| --- | --- |
| `listTasks_tasks` | This conversation's tasks only, even when another conversation has the same coordinator and the same delegates |
| `listTasks_tasks` | This conversation's tasks, and the steps its coordinator filed for itself, only: never another conversation's, even with the same coordinator and the same delegates |
| `getTask_tasks` | One task whole: its brief, its fields, how it stands, its delegate's status note, and its output |
| `createTask_tasks` | Files a task: it starts at once, after its `deps`, or, with `held: true`, when you release it |
| `updateTask_tasks` | Before the task starts: changes any of its fields, its delegate included, holds it (`status: "held"`) or releases it (`status: "pending"`). Until it finishes: sends it a `message`, or cancels it (`status: "cancelled"`), with nothing said in the conversation |
Expand Down
8 changes: 3 additions & 5 deletions apps/docs/docs/workforce/ui.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,15 +123,13 @@ import { BoardList } from "@flow-state-dev/react";
/>
```

With `live`, the list follows the session you pass and reads the board again whenever that session records a change to it. A task filed in a conversation is recorded in that conversation's session, so pass the conversation's id, as above. Each new task then shows up in every tab that has the list open.
With `live`, the list reads the board again whenever a task on it changes, from whichever session or server process the change comes. Pass the id of the session that files the tasks, usually the conversation, as above. A task filed there, and the same task settling later in its delegate's own task session, both show up in every tab that has the list open. A reply streaming in the conversation doesn't make the list read.

The reads and the live stream both go through `client`, so the stream carries the same credential to the same server as the reads. A client that can only read (it has `resources.listCollectionItems` but no `sessions.stream`) can't take `live`, and TypeScript rejects that pair.
The reads and the live subscription both go through `client`, so the subscription carries the same credential to the same server as the reads. A client that can only read (it has `resources.listCollectionItems` but no `subscribe`) can't take `live`, and TypeScript rejects that pair.

Rows already on screen stay there while the list reads again.

A change recorded in a different session does not reach a live list until something makes it read again: a remount, a reload, or the next change in the session it follows. A delegate working a task in its own task session is the usual example. So `live` suits watching tasks arrive as they're filed. To see where the work has got to, read the board on mount, as `BoardColumns` does.

Each live list holds its own connection to its session's stream while it is mounted, the same kind [`useSession`'s `live`](../client/react.md#hearing-requests-you-didnt-send) opens. A page that also follows that session with `useSession(..., { live: true })` holds two connections to it. If the server doesn't offer the stream, or refuses it, the list reads once, as if you hadn't asked, with no error.
A live list shares its client's one connection with every other subscription on that client (see [Keeping a screen current](/guides/realtime)). On a host that can't push, or while the connection is down, it reads every 3 seconds instead.

Each row shows the task's `title` (its `goal` if there is no title, its `id` if there is neither), its status word, and the assignee when there is one. The words are the ones the columns are headed with (`pending`, `in_progress`, and so on). A task in a status the list doesn't recognise shows with its own word. No row is hidden. A row without a `createdAt` follows the dated ones.

Expand Down
30 changes: 26 additions & 4 deletions apps/docs/guides/realtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,17 +29,21 @@ function TaskList({ sessionId }: { sessionId: string }) {
);

useEffect(() => void refresh(), [refresh]); // the first read
useSubscription([topic.session(sessionId)], refresh, { pollIntervalMs: 3000 });
useSubscription(
[topic.session(sessionId, { resource: "tasks" }), topic.session(sessionId, { resource: "plan" })],
refresh,
{ pollIntervalMs: 3000 },
);

return <ul>{tasks.map((task) => <li key={task.id}>{task.title}</li>)}</ul>;
}
```

On the Node host, `refresh` runs as soon as the change is saved: the server sends the notice once the change can be read, and no timer is involved, so the delay is the network and your read. A burst of changes runs it once more after the read in flight finishes, not once per change. The hook doesn't read on mount, so keep the first read where your screen already makes it.
On the Node host, `refresh` runs as soon as the change is saved: the server sends the notice once the change can be read, and no timer is involved, so the delay is the network and your read. A burst of changes runs it once more after the read in flight finishes, not once per change. The hook doesn't read on mount, so keep the first read where your screen already makes it. It subscribes through the provider's client; an app that builds its own client, with its own `fetcher`, passes it as `client` so the socket signs in the same way.

| Topic | What changes it covers |
|-------|------------------------|
| `topic.session(id)` | One session: its requests, their items, and runs started under it. |
| `topic.session(id)` | One session: its requests, their items, runs started under it, and changes to its task boards. |
| `topic.user()` | The signed-in user's own scope. |
| `topic.org()` | The signed-in user's organization. |

Expand All @@ -56,7 +60,25 @@ useSubscription([topic.session(sessionId)], (notice) => {
});
```

`kind` is `"items"`, `"request"`, `"run"`, `"state"`, `"resource"` or `"resync"`. `"state"` means the scope's state was written, and `"resource"` that a resource under it was, with the resource's path in `topic.resource`. `origin.requestId` names the request that made the change, when one did. Read everything on `null` and on `"resync"`: the screen may have missed something.
`kind` is `"items"`, `"request"`, `"run"`, `"state"`, `"resource"`, `"board"` or `"resync"`. `"state"` means the scope's state was written, and `"resource"` that a resource under it was, with the resource's path in `topic.resource`. `"board"` means a task on one of the session's task boards changed, with the board's id in `topic.resource` (see [Task boards](#task-boards)). `origin.requestId` names the request that made the change, when one did. Read everything on `null` and on `"resync"`: the screen may have missed something.

Narrowing the topic does the same job with less code. A screen subscribed to `topic.session(id, { resource: "tasks" })` only hears changes to that board, so a long reply never wakes it.

## Task boards

A task board's change is announced on the session that filed the task, narrowed to the board, whichever session or process made the change. A conversation's delegate settles its task in a task session of its own, and the conversation's board screen still hears of it at once. Subscribe the conversation's topic narrowed to each board your read returns:

```ts
useSubscription(
[topic.session(conversationId, { resource: "tasks" }), topic.session(conversationId, { resource: "plan" })],
refresh,
{ pollIntervalMs: 3000 },
);
```

Workforce's `listTasks_tasks` read returns the conversation's board and its planning worker's own steps, which sit on the `plan` board, so a screen of that read subscribes both. Subscribing `plan` is harmless when the flow has no planning worker.

`BoardList` with `live` does this for you, for the one board it draws. Its `client` needs `subscribe` (see [A board as a list](/docs/workforce/ui#a-board-as-a-list)).

## Outside React

Expand Down
2 changes: 1 addition & 1 deletion apps/kitchen-sink/components/flow-state/tool-naming.ts
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ function lineRange(args: Fields): string | undefined {
/**
* How a workforce or task tool says what it did, from its args and, once the
* call is done, its result. Never an id: a task or message id means nothing to
* the person reading, so a task is named by its title, else its goal.
* the user reading, so a task is named by its title, else its goal.
*/
const WORK_TOOLS: Record<string, (args: Fields, output: Fields | undefined) => string> = {
readProjectSource: (args, output) => {
Expand Down
Loading
Loading