Repository navigation
spec(FIX-2412): Live roster read from workforce/browser - #4733
Conversation
The workforce client gains one roster watch on client.subscribe; Kitchen Sink, Shift Manager and the Teammates lab adopt it and drop their one-shot reads, and Kitchen Sink's rail derives its coordinators from the roster. The existing-conversation flag is cut (D2). Includes a checker that lists every roster read in the three apps. 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. |
Second look + architecture pass (read-only; direction-level only)Overall: the approach is sound. A single 1. Lift the coalescer into
|
There was a problem hiding this comment.
/simplify review (spec FIX-2412)
Verdict: approve the direction. This is a spec-only PR, but the proposed implementation shape looks like the right tradeoff for ER-3: one place that knows the roster’s two collection paths, three apps delete one-shot reads and the hand list, and the accepted coalescer copy is explicitly filed to FIX-2551. I do not see a materially simpler approach that still meets the epic goal without either triplicating path logic (FIX-2466 per-app shape) or adopting React’s Roster panel (wrong collection, wrong UI ownership).
What reads as well simplified
- D1 (
watchRosteron@flow-state-dev/workforce/browser) matches howliveScopeDriveralready works in react (client.subscribe+ coalesced reads + manifest prefix), but keeps path knowledge in workforce whereroster()already lives. - D2 (no conversation flag) is the right cut: a field the watch cannot keep live would be worse than omitting it; coordinators from
flowremovesSHELL_COORDINATORSwithout a parallel marker concept. - Scope discipline: FIX-2409 / FIX-2411 boundaries are clear; leaving the snapshot roster read is honest debt, not hidden scope creep.
- Evidence:
poc/roster-reads/check.mjsran clean on this branch (286 files, 13 sites). That is proportionate design evidence—not production machinery—and the planted control is a nice enforcer.
Where complexity might still be trimmed (implementation phase—not blockers)
These are suggestions to weigh, not spec gate failures:
- Kitchen Sink rail vs Workers panel — The spec diff shows the panel on
watchRosterwhile the rail keeps(await workforce.roster())at each listing. That is coherent with FIX-2411 owning when the listing re-runs, but it is a second roster read path in the same app. If the rail listing re-run cadence is slower than the panel watch, a coordinator added by hire could lag on the rail even whena:within-1spasses forTeamPanel. Consider deriving coordinator ids from the same watch snapshot the panel uses (or documenting in the goal which surfaces must passa:within-1svs rail-only checks). - Teammates
LabAdapter.listWorkers— The adapter already exposes manywatch*verbs (FIX-2466 shape). TurninglistWorkersinto a watch is consistent, but it touchesLabAdapter,fake-lab, and contract tests more broadly than callingworkforce.watchRosterinside the adapter implementation while keeping a Promise bootstrap API—or addingwatchWorkersbesidelistWorkers. Worth a quick implementer choice: minimize adapter surface churn vs. align all live roster UI with one unsubscribe pattern. - FIX-2551 sequencing — Waiting for an un-specced FIX-2551 is reasonably rejected, but if the lift is “export
coalescedReads+ prefix match from client/react internal,” doing that in the same implementation PR (or immediately after) may be cheaper than maintaining a third copy that must stay byte-aligned with react’sliveScopeDriver. - Goal harness —
goals/realtime/roster-follows-hires/does not exist yet (expected for a spec). When authoring it, cloning the structure/signals ofgoals/realtime/app-views-read-on-notice/(crossing bus, idle read floor,GOAL_CONTROLnegatives) will avoid inventing a second goal dialect. - Third-party libraries — TanStack Query / Firestore-style invalidate-on-event is a useful analogy (noted in Analysis) but would not replace
client.subscribehere without re-implementing transport semantics; no change recommended.
Performance (spec-level)
- Accepted double read in Shift Manager (snapshot + watch) until FIX-2409 is the main ongoing cost; coalescing + one watch per connection is the right mitigation.
- Bare user-topic notices triggering a roster re-read is an intentional false positive; spec already bounds with coalescing and “only when roster changed” callbacks.
Process nit
Analysis notes it was not run by a fresh sub-agent; fine for draft, but a coordinator re-run before merge is still worth it per your own gate note.
Summary: The spec is tighter than the problem it replaces (hand list, stale one-shots, duplicated subscribe logic). I would not redirect to a different architecture unless FIX-2551 lands first and exposes a generic multi-collection watch helper—otherwise D1 stands.
Sent by Cursor Automation: Review For Best Approach
|
|
||
| // Kitchen Sink: the rail's coordinators | ||
| -SHELL_COORDINATORS.map((worker) => workforce.ensureWorkerSession({ worker })) | ||
| +(await workforce.roster()).filter((w) => isCoordinatorFlow(w.flow)).map((w) => workforce.ensureWorkerSession({ worker: w.id })) |
There was a problem hiding this comment.
Possible simplification (soft): Panel moves to watchRoster while the rail example still await workforce.roster() on each listing. That splits live state across two mechanisms in one app. If FIX-2411’s re-run cadence is coarser than the panel watch, the rail could miss a newly hired coordinator even when TeamPanel passes a:within-1s. Consider sharing one watch snapshot (filter coordinators client-side) or spell out in the goal which UI surfaces are in a:within-1s vs d:rail only.
|
|
||
| | How we verify | | | ||
| |---|---| | ||
| | **Goal check** | `goals/realtime/roster-follows-hires/` · model `n/a` (the roster flow's actions write) · run by the implementer at completion · verdict on the implementation PR | |
There was a problem hiding this comment.
When you add this goal, strongly consider cloning goals/realtime/app-views-read-on-notice/ (crossing double, idle read assertions, negative GOAL_CONTROLs). That keeps realtime verification consistent and avoids a one-off harness dialect for the same subscribe/coalesce semantics.
|
|
||
| ## Settled | ||
|
|
||
| - **Every roster read in the three apps is listed** — **CONFIRMED** by |
There was a problem hiding this comment.
Adapter shape (implementer fork): Teammates already uses watch* on LabAdapter for live views. Making listWorkers itself a watch aligns with that, but it is a wider interface/fake-lab churn than implementing the watch inside the adapter (or adding watchWorkers) while App.tsx subscribes once. Not wrong—just the main place I’d double-check for the smallest diff.
| | The debt | | | ||
| |---|---| | ||
| | **Removes** | `SHELL_COORDINATORS` and its test case; KS's one-shot read and Retry; SM's per-snapshot roster read in `useRoster` and DELEGATES' own read; Teammates' `listWorkers` and its re-reads after hire and fire | | ||
| | **Adds** | A third copy of the coalescer and the path match, in workforce. Accepted: the shared one is react-internal. Paid by [FIX-2551](https://linear.app/fixpoint-labs/issue/FIX-2551) | |
There was a problem hiding this comment.
If FIX-2551’s lift is mostly exporting react/client internals (coalescedReads, prefix match), consider doing that export in the implementation PR before copying a third time—the spec’s ‘wait’ decision is reasonable for gating, but the copy is the highest drift risk called out in sign-off.
| for (const site of unclassified) console.error(`UNCLASSIFIED ${site.file}:${site.line} ${site.text}`); | ||
| for (const key of missing) console.error(`MISSING ${key} (classified, no longer found)`); | ||
| if (unclassified.length > 0 || missing.length > 0) process.exit(1); | ||
| console.log("every roster read classified"); |
There was a problem hiding this comment.
Good enforcer. Implementers should re-run this after edits (keys are line-fragment fragile) and extend the scan if a new helper wraps roster() without matching SITE—the README already calls out that limit.


Requested by Jake · project thread
WORKER.mdto Kitchen Sinksupport.helponly. A test fails until a person edits a listGoal: when a worker is hired, forked, edited or fired, from any tab or by any worker's turn, the roster in Kitchen Sink, Shift Manager and the Teammates lab shows it without a reload or a Retry, and the Kitchen Sink rail lists the coordinators that the roster names, with no list kept by hand.
The check reads what the view of each app shows, and counts its reads. Check:
goals/realtime/roster-follows-hires/, modeln/a. Controls:GOAL_CONTROL=read-oncemust faila:within-1sandc:no-push;GOAL_CONTROL=hand-listmust faild:rail. Why this goal: SPEC.md.Each row is the roster view of one app. Left: a read that occurs one time. Right: the same view on the one watch of the workforce client.
How: the workforce client gets one method,
watchRoster. It usesclient.subscribeon the user topic. When a notice names one of the two worker collections, it reads the roster again. The three apps use it and delete their one-time reads.Sign off
The goal, at that size. All three apps follow the roster, and the rail gets its coordinators from the roster. If wrong: a watch that no app uses, or an app that shows a hire only after a reload.
The debt: net down. The hand list, a Retry and four one-time reads go. One method and a copy of the read coalescer come in; FIX-2551 pays the copy. If wrong: a third copy that drifts before FIX-2551.
The roster gets no conversation flag; coordinators come from the flow of each worker · D2
Figure:
specs/issues/FIX-2412/figures/d2-no-conversation-flag.svg(no conversation flag, chosen, beside a coordinator marker and a flag).It comes down to this: a new session sends no notice that the roster hears, so the flag becomes wrong. If wrong: an app that needs the flag reads the conversations of each worker. This is the one to weigh: it cuts a part of what the issue asked for.
The roster watch is one method on the workforce client · D1
Figure:
specs/issues/FIX-2412/figures/d1-watch-on-workforce.svg(on the workforce client, chosen, beside in each app and the React Roster panel).It comes down to the storage paths: only workforce knows them, and in each app they are three copies. If wrong: a public method that we keep beside a shared helper.
Open: none. Reasons and what lost: DECISIONS.md.
Analysis: right approach, with one cut (D2). It was run in the author's session, not by a fresh agent. DECISIONS.md → Analysis.
Reviewers · look here
Not here: the Shift Manager snapshot refresh (FIX-2409), the live rail session list (FIX-2411), display names for your own workers (FIX-2526).
Spec · Decisions · Linear FIX-2412 · epic FIX-2369 · builds on FIX-1506, FIX-2428 · merges after human approval and required checks
Checker — every roster read in the three apps (throwaway)
It answers: is the list of roster reads that the spec moves complete? It is throwaway evidence, not production code.
How to review this — altitude, what's in scope, what's deliberately unsettled
This is a direction set, not an implementation and not a build plan. Reviewing it well means
answering one question: is this the right approach?
In scope to challenge:
SPEC.md— is the goal the real need at full size,for the people named, or a smaller goal that would let us call this done early? Would the
named check fail if the goal were not met?
docs/philosophy.md?DECISIONS.md— that's the sign-off surface.SPEC.md→ What's already here, and the debt — an existing primitive,method or prior design the change overlaps and doesn't name; something it adds that is debt
and isn't listed; a net verdict the tables don't support.
piece it considered, or that is a second mechanism for something we already have
(
orchestration.md).design.
Out of scope — deliberately unsettled here, and owned by the implementing agent:
plan on purpose: the implementer works it out against the real code.
or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
decisions don't say is.
poc/are retained,not production code. Read them for directional evidence, not production completeness.
Their isolation from production/default discovery and absence of secrets or generated
dependencies are in scope; retention is not permission to weaken repository checks.
One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.
Feedback in the second list is welcome and gets recorded verbatim in
DECISIONS.md → Notes from reviewfor the implementer to weigh against real code. It will notbe argued with, and it will not be folded into the design prose. Please don't re-raise it: one
mention is enough.
The one exception is the POC. Line-level feedback on it is dropped, not recorded — there
is nothing for an implementer to weigh about code that isn't shipping. Feedback about its
direction is not line-level and is treated like any other above-the-bar finding.
Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.
https://claude.ai/code/session_01NczDiGg5ZaksUKbmqvc8F8
Generated by Claude Code