Repository navigation
FIX-2412: the roster follows hires, forks, edits and fires in every app - #4747
Conversation
…ager and Teammates (FIX-2412)
- workforce: WorkforceClient.watchRoster(onRoster, { onError }) on the browser
entry, built on client.subscribe (user topic, both worker collections'
paths, the client's fallback timer only). WorkforceClientSource adds subscribe.
- kitchen-sink: TeamPanel follows the watch (Retry gone); the rail reads its
coordinators off the roster's flows; SHELL_COORDINATORS removed.
- shift-manager: useRoster is one shared watch per connection; DELEGATES
picks from it without re-reading the delegates.
- teammates: LabAdapter.watchWorkers replaces listWorkers; the App boots on
the watch and drops its re-reads after hire and fire.
- goal: realtime/roster-follows-hires with read-once, hand-list and timer controls.
- docs: durable-hire, ui, workforce and shift-manager READMEs, Teammates table.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGg5ZaksUKbmqvc8F8
|
The latest updates on your projects. Learn more about Vercel for GitHub.
3 Skipped Deployments
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
@codex review |
Second look + architecture passReviewed against the approved direction (D1/D2), so none of this re-argues the spec. Overall the shape is right: one push-driven method on the workforce client, apps drop their own reads and timers. The goal check and the red-state evidence are solid. Findings, most important first. 1. Teammates: a failed
|
There was a problem hiding this comment.
Code Snob — already tight. No POC.
Head 03069691bd07e291f6e58ff773dc8276bf835bcc. I read packages/workforce/src/workers/client.ts (watchRoster, rosterMayHaveChanged, coalesced), packages/react/src/internal/coalescedReads.ts, packages/shift-manager/src/lib/roster.ts and workforce.ts, packages/shift-manager/src/components/DelegatesPanel.tsx, apps/kitchen-sink/components/team-panel.tsx, apps/kitchen-sink/lib/rail-sessions.ts, labs/teammates/src/App.tsx, labs/teammates/src/adapter.ts, labs/teammates/test/fake-lab.ts, and goals/realtime/roster-follows-hires/run.mts.
A rewrite would not shrink the contract:
coalescedis the recorded copy ofcoalescedReadsuntil FIX-2551. Inlining it, or importing the react internal, is the split this PR left filed.joinWatchis the one watch per connection.useWorkforceis memoized on the client.roster-screen.test.tsxreturns a new workforce object on each render, and the ref is what keeps that from restarting the watch. Dropping the ref moves that constraint onto every caller. The view set stays, because a listener can leave duringtell.- Kitchen Sink's
useRosteris the one effect. The rail'sroster()filter is what replacedSHELL_COORDINATORS. The rail stays off the watch. - The Teammates boot effect is the first roster landing the page and later rosters redrawing the list.
failureOfis the 502 the connection screen shows. The fake's stringify skips conversation notifies that leave the roster the same; without it every message opens every conversation again. - The goal file mounts three surfaces (panel rows,
useRoster,watchWorkers) and patches three controls. A shared grader still walks those three views.
The changeset, durable-hire.md, and the workforce README are the public method. Cutting the comments leaves the same code.
Fold nothing. D1, D2, the rail, DELEGATES, and the coalescer copy stay as recorded.
Sent by Cursor Automation: Code Snob
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 03069691bd
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Simplify / architecture
Problem: Roster UIs in Kitchen Sink, Shift Manager, and Teammates stayed on one-shot roster() reads, so hires/forks/edits/fires from another tab or a worker turn did not show up without reload/retry.
Verdict: The chosen shape matches FIX-2412 D1 and is simpler than the main alternatives (each app re-implementing subscribe + path matching, or adopting React's live Roster panel on a different collection). Centralizing watchRoster on @flow-state-dev/workforce and keeping app code thin (Teammates delegate, KS useEffect, SM shared watch) is the right local minimum.
I do not think the PR over-engineered the core primitive. The extra complexity that looks heavy is mostly Shift Manager's WeakMap refcount — that is package-local, solves real multi-surface + dual first-read roster-session races, and is appropriate there. Kitchen Sink's inline hook is fine for a single panel today.
What I'd treat as follow-up (not blockers):
| Item | Note |
|---|---|
| FIX-2551 | coalesced in workforce duplicates react's coalescedReads — already accepted in spec; merge when that issue lands. |
Second watchRoster on one client |
Spec calls this a review finding; keep one watch per connection (SM pattern) if KS grows more roster surfaces. |
JSON.stringify dedup |
Saves callbacks, not I/O; fine at current roster sizes. |
Rail railSessions |
Still one-shot roster() per coordinator listing — intentional per goal (live rail is FIX-2411). |
| Goal driver ~456 lines | High-value cross-app proof; optional split into host/mount/assert modules if it churns often. |
Alternatives considered (and why I wouldn't pivot this PR):
useSubscriptionin React only — doesn't help Teammates/goal driver; still need workforce path knowledge.- SWR/React Query — fights the locked
client.subscribe+ single fallback timer model (FIX-2428). - Shared
@flow-state-dev/workforce/reacthook — nice DX later; not required to ship FIX-2412.
Verification: pnpm --filter @flow-state-dev/workforce test (includes watch-roster.test.ts) — 1783 tests passed on this branch.
Approving directionally; inline notes are nits and guardrails for follow-ups.
Sent by Cursor Automation: Review For Best Approach
| * queues exactly one more. A copy of react's internal `coalescedReads`, | ||
| * until FIX-2551 lifts one into the client. | ||
| */ | ||
| function coalesced(read: () => Promise<void>): { request: () => void; close: () => void } { |
There was a problem hiding this comment.
Accepted debt per D1/FIX-2551 — this mirrors packages/react/src/internal/coalescedReads.ts. When FIX-2551 lands, delete this copy and import the shared helper so workforce + react + lab adapters do not drift.
| const reads = coalesced(async () => { | ||
| try { | ||
| const entries = await client.roster(); | ||
| const seen = JSON.stringify(entries); |
There was a problem hiding this comment.
Dedup runs after a full roster() round-trip — correct trade today. If bare user resource notices get noisy in production, tighten rosterMayHaveChanged rather than skipping coalesce (spec prefers false-positive reads over staleness).
| const reads = new WeakMap<object, { readAt: number; read: Promise<RosterEntry[]> }>(); | ||
| const watches = new WeakMap<object, SharedWatch>(); | ||
|
|
||
| function joinWatch(client: object, workforce: WorkforceClient, view: (read: RosterRead) => void): () => void { |
There was a problem hiding this comment.
Refcounted shared watch is the heaviest glue here but justified for many SM surfaces + avoiding dual first-read roster-session races. Consider a one-line module invariant: WeakMap key = Lab client identity; last subscriber stops watchRoster.
| } | ||
|
|
||
| /** The user's roster as the workforce client's watch reports it, and the last read's failure until one lands. */ | ||
| function useRoster(workforce: WorkforceClient): { |
There was a problem hiding this comment.
Name collision with Shift Manager's exported useRoster(). Fine for one panel; if KS adds another roster consumer, use SM's shared-watch pattern — D1 treats a second watchRoster on the same client as a review finding.
| const list: RailClient["sessions"]["list"] = async (options) => { | ||
| const flow = options?.flowKind; | ||
| if (flow === undefined || !isCoordinatorFlow(flow)) return await client.sessions.list(options); | ||
| const coordinators = (await workforce.roster()).filter((worker) => isCoordinatorFlow(worker.flow)); |
There was a problem hiding this comment.
Live watch on the panel; one-shot roster() here for coordinator listing is intentional (goal leg d; live rail is FIX-2411). A FIX-2411 pointer comment would help the next reader.
…ammates roster After the page lands, each roster change applies even when one teammate's conversation fails to open; that teammate keeps the conversation it had, or opens it when picked. Before landing, a failed open still shows the unreachable screen with Retry. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NczDiGg5ZaksUKbmqvc8F8
|
Architect: not approving yet. Two second-look findings in — FSD Architect |
…hat lands A hire selects its teammate, with the cursor in its composer, once the row and its conversation land; a fire picks the next teammate from the roster that no longer lists the fired one, never from the list drawn before the call. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NczDiGg5ZaksUKbmqvc8F8
|
Both are fixed in 5bc8478.
Teammates: typecheck is clean and 187/187 tests pass. Generated by Claude Code |
…-uxpn8e # Conflicts: # apps/kitchen-sink/lib/rail-sessions.ts # apps/kitchen-sink/test/rail-sessions.test.ts
…-uxpn8e # Conflicts: # apps/kitchen-sink/lib/rail-sessions.ts
…-uxpn8e # Conflicts: # labs/teammates/src/App.tsx # labs/teammates/src/adapter.ts # labs/teammates/test/fake-lab.ts
Head branch was pushed to by a user without write access


Requested by Jake · project thread
The problem
Three apps show a user's workers: Kitchen Sink, Shift Manager and the Teammates lab. Each one read the roster once. A worker hired, forked, edited or fired in another tab, or by a worker's own turn, did not appear until a reload or a Retry. Shift Manager's DELEGATES picker did not show it until the screen remounted. A hire looked like it had failed.
Kitchen Sink's rail also kept its coordinators in a hand-written list (
SHELL_COORDINATORS). A second coordinatorWORKER.mdstayed off the rail, and a test failed, until someone edited that list.What this does
watchRoster(onRoster, { onError }), on@flow-state-dev/workforce/browser. It reads the roster, and reads it again when the client'ssubscribehears a change under either worker collection on the user's topic. Where push can miss a change, the client's own fallback timer reads every 3 s. The views keep no timer of their own.SHELL_COORDINATORSand its test case are gone.The goal check
goals/realtime/roster-follows-hires/passes: each view shows a hire, a fork, an edit, a fire and a no-stream hire within 1 s (slowest 24 ms), makes 0 roster reads over 10 s idle, and another user's views read nothing. Each of its three controls fails where it must.What's asked of you
This implements the approved direction (D1 and D2 as recommended: no existing-conversation flag on a roster row). Nothing new is yours to decide.
Parts worth reviewing closely
packages/workforce/src/workers/client.ts→rosterMayHaveChanged. Is the path match right? It reads on aresourcenotice underworkforce/workers/orworkforce/standard-workers/, on one with no path, onresync, and onnull. A false no leaves every app's roster stale; a false yes costs one read.packages/shift-manager/src/lib/roster.ts→joinWatch. One watch per Lab connection, shared by every view and stopped by the last one.useRosterkeys the watch on the connection's client only and holds the workforce client in a ref, because a test double (or a careless caller) that hands back a new workforce client on each render would otherwise restart the watch in a loop. Is the ref the right call, or should the hook depend on the workforce client too?labs/teammates/src/App.tsx. The boot now rides the watch: the first roster lands the page, later ones redraw the list. After this tab's own hire, the new row arrives through the watch, so the new teammate opens when its row lands, not before..changeset/roster-watch.md.WorkforceClientSourcenow includessubscribe. A client fromcreateClienthas it; a hand-built source does not. The changeset calls this breaking for a hand-built source. Isminorright?Spec
specs/issues/FIX-2412/(spec PR #4733, merged) · Linear FIX-2412 · epic FIX-2369.How to review this — altitude, what's in scope, what's deliberately unsettled
How to review this. This implements an approved spec — the approach and the numbered decisions in its
DECISIONS.mdare already signed off by a human, so please review the code against that direction, not the direction itself. The canonical set is retained atspecs/issues/FIX-2412/onmain; Linear links to it and the original merged spec PR, which keeps review history. Follow-up amendment PRs explain later direction changes. Current architecture docs remain the authority for shipped behavior (BP-037).Most valuable here: correctness on the second path (the legacy shape, the null boundary, the concurrent case, the cancel path), anything deriving an auth or routing decision from caller-controllable input, and a behaviour the tests assert around rather than on.
Already settled upstream: the approach and every decision in the spec's
DECISIONS.md(human-approved — if one is wrong, say so as a spec finding and it gets folded back; don't re-argue it inline), and the conventions indocs/contributing/best-practices.md.Engineering calls — decided along the way, no product sign-off needed
a:within-1scovers the Workers panel, andd:railcovers what the rail lists. If wrong: the rail and the panel disagree until the rail lists again.LabAdapter.listWorkersbecamewatchWorkers(onChange, onError), beside the otherwatch*verbs (FIX-2466). The fake lab follows it. Retry starts a new watch.coalescedin the workforce client is a third copy of react's internalcoalescedReads, as the spec's debt table accepts; FIX-2551 lifts one into the client. Lifting it here would widen this PR into client API changes.durable-hire.md→ Keep the roster current, one line inui.md, the workforce README's client paragraph and example, Shift Manager's Roster paragraph and the Teammates read table.Everything else — verification, red states, the spec checker, files
Goal check (
cd goals && pnpm tsx realtime/roster-follows-hires/run.mts):GOAL_CONTROL=read-once: FAILa:within-1s(all 15 never shown) andc:no-push(3 views never);a:quiet,b,dheld.GOAL_CONTROL=hand-list: FAILd:railonly (listed["support.help"]).GOAL_CONTROL=timer: FAILa:quiet(4 reads per view over 10 s idle) andb:other-user(4 reads per bob view); the rest held.b's "never shows alice's workers" half. The server scopes the read to its caller, and no app-side patch can break that.Unit tests and red states
packages/workforce/test/watch-roster.test.ts(5 cases), red before the method existed. Blast radius, one perturbation each: match every path, no coalescing, keep the last roster after a failure, another pace, report after stop. Each reddened exactly its own case and nothing else.test/team-panel.test.tsxandtest/rail-sessions.test.ts: red against the previous panel and the hand list (5 of 6 cases failed for the intended reason).test/roster-screen.test.tsx(one watch per connection; a hire reaches Roster and TEAMS with no new snapshot) andtest/coordinator-view.test.tsx(DELEGATES offers a hire with no delegates re-read): red against the previous sources. Removing the per-connection sharing reddens the one-watch case only.test/roster-follows.test.tsx: making the App ignore every roster after the first reddens both cases, and the four existing hire/fire cases too.The spec's checker (
specs/issues/FIX-2412/poc/roster-reads/check.mjs) exits 1 after this change, as expected for spec-time evidence: the 9 moved and 1 removed sites are now MISSING, the 3 "stays" sites are still found, and one new site, the rail'sroster()read at each listing, is unclassified. That read is the one the spec decided.Files
packages/workforce:watchRosteron the client;WorkforceClientSourceaddssubscribe; test; README.apps/kitchen-sink:TeamPanelon the watch, Retry removed; the rail reads coordinators off the roster;SHELL_COORDINATORSand its test case removed; tests.packages/shift-manager:useRosteron one shared watch per connection (noreadAt); DELEGATES usesuseRoster; test doubles gainwatchRoster; README Roster paragraph.labs/teammates:watchWorkersreplaceslistWorkers; the App boots on the watch and drops its re-reads after hire and fire; fake lab; tests; README.goals/realtime/roster-follows-hires/: the goal and its three controls.apps/docs:durable-hire.md,ui.md..changeset/roster-watch.md: workforceminor, shift-managerpatch.The snapshot's own roster read in
packages/shift-manager/src/lib/reads.tsstays (FIX-2409).Generated by Claude Code