Skip to content

spec(FIX-2412): Live roster read from workforce/browser - #4733

Merged
jhoffner merged 1 commit into
mainfrom
spec/FIX-2412
Nov 4, 2026
Merged

jhoffner merged 1 commit into
mainfrom
spec/FIX-2412

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 4, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Someone who… Today After
has Kitchen Sink open when a worker is hired, forked or fired elsewhere The Workers panel keeps its first read until a reload The panel shows the change in a few seconds (Kitchen Sink has no push, so it reads on the client's one timer)
uses Shift Manager when Shift Coordinator hires a worker Roster shows it at the next snapshot read. The DELEGATES picker does not show it Roster, TEAMS and the DELEGATES picker follow the roster
uses the Teammates lab when a worker is edited or fired in another tab The list keeps the old worker until a reload The list follows the roster
adds a second coordinator WORKER.md to Kitchen Sink The rail shows support.help only. A test fails until a person edits a list The rail shows each worker on the coordinator flow, from the roster
opens a worker for the first time Talk finds or starts the conversation The same. The roster does not tell about conversations (D2)

Goal: 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.

flowchart LR
  I["serve · crossing bus · alice and bob"] --> H["alice's other tab · hire, fork, edit, fire"]
  H --> V["each app's own view · KS panel · SM roster · Teammates list"]
  N["host with no push"] --> V
  K["KS rail · a tree with two coordinators"] --> V
  V -->|"each change within 1 s · 0 reads idle · bob reads nothing"| P["PASS · goal met"]
  C["control · read-once"] -.-> V
  V -.->|"under the control"| F["must FAIL · a:within-1s"]
Loading

The check reads what the view of each app shows, and counts its reads. Check: goals/realtime/roster-follows-hires/, model n/a. Controls: GOAL_CONTROL=read-once must fail a:within-1s and c:no-push; GOAL_CONTROL=hand-list must fail d:rail. Why this goal: SPEC.md.

Four roster views in three apps. Today each reads one time, or from a hand-kept list. After, each follows one watch on the workforce client

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 uses client.subscribe on 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

  • Decisions → D2. Is a flag that becomes wrong worse than no flag? Is there an app that must show "you talked to this worker"?
  • Spec → what stays. Shift Manager reads the roster in its snapshot and in the watch. FIX-2409 owns the snapshot. Is this boundary correct?
  • Decisions → decided, not asked. The watch hears the user topic only. Standard workers change only when the server restarts, and the reconnect reads again.

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)
node specs/issues/FIX-2412/poc/roster-reads/check.mjs                         # 13 sites: 9 move, 1 removed, 3 stay
FIX2412_CONTROL=plant node specs/issues/FIX-2412/poc/roster-reads/check.mjs   # must exit 1

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:

  • The goal and the problem framing in 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?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • The debt in 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.
  • Builds on / Adds in that same section — an Adds item that does not name the existing
    piece it considered, or that is a second mechanism for something we already have
    (orchestration.md).
  • A case a person would hit that the people table misses, when it would invalidate the
    design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • The build plan. Order, file-level changes, the test list, the PR split. The set has no
    plan on purpose: the implementer works it out against the real code.
  • Names, signatures, file paths, and module layout, beyond the few a decision locks.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Edge cases that don't change the approach. The implementer's tests own them.
  • Documentation wording. It is written at implementation, against what shipped.
  • Micro-optimizations and style preferences.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    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 implementation polish. Experiments under the owning spec's 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 review
for the implementer to weigh against real code. It will not
be 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

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
@jhoffner jhoffner added the spec label Nov 4, 2026 — with Claude
@linear-code

linear-code Bot commented Nov 4, 2026

Copy link
Copy Markdown

FIX-2412

@vercel

vercel Bot commented Nov 4, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
flow-state-dev-build-site Ready Ready Preview Nov 4, 2026 9:45pm UTC
3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Nov 4, 2026 9:45pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Nov 4, 2026 9:45pm UTC
flow-state-dev-ui Ignored Ignored Nov 4, 2026 9:45pm UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-04T21:47:04.355805Z 862b0a9 PR opened
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

jhoffner commented Nov 4, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (read-only; direction-level only)

Overall: the approach is sound. A single watchRoster on the workforce client that composes client.subscribe and re-reads through roster() is the right owner for the noun. D1 and D2 hold up. One finding changes the approach; the rest are notes.

1. Lift the coalescer into @flow-state-dev/client in this change, not a "third copy" later (changes the approach)

The spec accepts a third copy of the coalescer and path match "until FIX-2551". I checked the code, and the copy isn't needed:

  • packages/react/src/internal/coalescedReads.ts is 38 lines. scopeNotices.ts is 47 lines (LIVE_POLL_MS, storagePrefixOf, mayBelongTo). Both are pure, with no React in them. scopeNotices imports only ResourceManifest.
  • @flow-state-dev/workforce already depends on @flow-state-dev/client, and react wraps client. So client is the one place both can import from without breaking a package boundary.
  • The spec says "the shared one is react-internal" and so "can't be imported". That is true only while it stays in react. Moving ~85 lines down to client is a smaller diff than writing a copy plus a follow-up issue.
  • This also makes the new copy unnecessary, and CLAUDE.md's coding convention says helpers shared across packages belong in a shared utils file, not inlined per package.
  • The spec's own Net verdict ("down") gets stronger: no new debt line, and no "drifts before FIX-2551" risk to sign off on.

Suggested shape: move coalescedReads, LIVE_POLL_MS, storagePrefixOf and mayBelongTo to client (internal or a small subpath). react re-imports them, and watchRoster imports the same ones. FIX-2551 then shrinks to whatever remains, or closes. The risk is touching react's live panels (FIX-1506), but it is an import move with the existing panel tests as the check.

If you'd rather keep the copy to keep this PR from touching react, then at least move the sign-off line. It should say the copy is a known BP-034-style duplicate with a dated owner, not "accepted".

2. Shift Manager reading the roster twice per screen (note)

"Leaves: SM reads the roster in the snapshot and in the watch" is a stated, owned boundary (FIX-2409). That is fine. But the goal check, a:quiet (0 reads over 10 s idle), counts reads at the fetcher. Make sure the snapshot's read is excluded from that count by construction, not by timing. Otherwise the check passes or fails on when FIX-2409 lands, not on whether this change works.

3. D2 (no conversation flag) agrees with the code

Coordinators are derivable from flow, and a flag that goes stale under a watch is worse than none. Cutting it is the right call, and the "what would change my mind" condition (a session-created notice from FIX-2411) is the right trigger to revisit it. I'd keep it surfaced as the sign-off item, as the PR does.

4. Smaller notes (implementer's call)

  • The "false yes costs a read" rule for bare notices means any user-scope write by an unrelated resource triggers a roster read. With onRoster firing only on change, the UI is safe. The a:quiet check should still include a case with an unrelated user-scope write.
  • watchRoster requires the source client to offer subscribe. State what happens on a source without it (throw at call, or one read and no watch), so apps with a test fake don't silently regress to read-once.

Generated by Claude Code

@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 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 (watchRoster on @flow-state-dev/workforce/browser) matches how liveScopeDriver already works in react (client.subscribe + coalesced reads + manifest prefix), but keeps path knowledge in workforce where roster() 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 flow removes SHELL_COORDINATORS without 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.mjs ran 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:

  1. Kitchen Sink rail vs Workers panel — The spec diff shows the panel on watchRoster while 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 when a:within-1s passes for TeamPanel. Consider deriving coordinator ids from the same watch snapshot the panel uses (or documenting in the goal which surfaces must pass a:within-1s vs rail-only checks).
  2. Teammates LabAdapter.listWorkers — The adapter already exposes many watch* verbs (FIX-2466 shape). Turning listWorkers into a watch is consistent, but it touches LabAdapter, fake-lab, and contract tests more broadly than calling workforce.watchRoster inside the adapter implementation while keeping a Promise bootstrap API—or adding watchWorkers beside listWorkers. Worth a quick implementer choice: minimize adapter surface churn vs. align all live roster UI with one unsubscribe pattern.
  3. 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’s liveScopeDriver.
  4. Goal harness — goals/realtime/roster-follows-hires/ does not exist yet (expected for a spec). When authoring it, cloning the structure/signals of goals/realtime/app-views-read-on-notice/ (crossing bus, idle read floor, GOAL_CONTROL negatives) will avoid inventing a second goal dialect.
  5. Third-party libraries — TanStack Query / Firestore-style invalidate-on-event is a useful analogy (noted in Analysis) but would not replace client.subscribe here 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.

Open in Web View Automation 

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 }))

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

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.

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

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.

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) |

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.

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");

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.

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.

@jhoffner
jhoffner added this pull request to the merge queue Nov 4, 2026
Merged via the queue into main with commit afd21c8 Nov 4, 2026
22 of 25 checks passed
@jhoffner
jhoffner deleted the spec/FIX-2412 branch November 4, 2026 23:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants