Skip to content

feat(engine,client,react): live session list with each row's state (FIX-2411) - #4749

Merged
jhoffner merged 16 commits into
mainfrom
claude/project-thread-i8owvt
Nov 5, 2026
Merged

jhoffner merged 16 commits into
mainfrom
claude/project-thread-i8owvt

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 4, 2026

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

What this does

A list of a user's sessions now stays current without a reload. Each row also shows whether its session needs you. This is the package half of FIX-2411, built from the approved spec (specs/issues/FIX-2411/, #4728). The Kitchen Sink rails come next as a separate PR stacked on this one.

  • engine: Every session or request write, except items and state-field deltas, now also publishes a run notice on the owner's user topic.
    • GET /sessions?include=status adds requestStatus to each row.
    • A suspended row also gets requestWaitsForUser. A question or approval counts as true; a wait on other work counts as false.
  • client: sessions.list({ include: ["status"] }). SessionSummary gains requestStatus and requestWaitsForUser.
  • react: New useSessionList hook. It re-reads on a run notice and when the page becomes visible.
    • FlowNavigator leaves read through it, so they are live.
    • Rows show a state mark and an age: ● Running, ◆ Waiting on you, ◇ Waiting, ! Interrupted, ✕ Failed, ! Incomplete.
    • sessionLabel, sessionRowState and sessionAge are exported.
  • docs: client and react READMEs, plus api/client, api/react, workforce/ui and guides/realtime.
  • changeset: minor bump for engine, client and react.

How it was verified

Check Result
Goal over real push: packages/node/test/live-session-list.test.ts (two clients on a served port) 2/2. A session created by another client shows up within 1 s, then in_progress, completed and failed each within 1 s. Another user's watcher reads nothing.
Control for the goal check With the user-topic notice removed in publish-writes.ts, test 1 fails with "not within 1000 ms".
change-bus.test.ts Delta writes publish nothing on the user topic. The session's own topic still hears them.
session-listing-status.test.ts A question gives suspended, true. A wait gives suspended, false. A completed session gives completed.
useSessionList.test.ts (7 tests) Reads on a run notice, not on items. Also reads on visibility. Without subscribe it reads once. It closes on unmount. Red state produced.
Suites engine 4370 passed · client 256 · react 559 · typecheck clean for engine, client, react and node.

Kitchen Sink under Next serves no push socket (/capabilities returns push: null), so its rail refreshes on the client's 3 s fallback timer. That's why the 1 s bound is proven on the Node host, as the amended spec says.


Generated by Claude Code

…IX-2411)

The owner's user topic hears a run notice for every write to one of the
user's sessions; the session listing can carry each row's latest request
status; useSessionList reads it live, and FlowNavigator's leaves read
through it and draw a state mark and an age.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFQ8qXgjG9CR9fxF2b
… docs (FIX-2411)

The listing says whether a suspended turn waits for the user, so a wait
on another worker's reply reads as Waiting, not as needing the person.
The user topic skips state field deltas, which a busy turn writes many
of. Documents useSessionList, include: "status" and the row marks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFQ8qXgjG9CR9fxF2b
The goal check for the package change: a rail on topic.user() hears a
session another client creates, its turn running, and its failure,
each within a second, and another user's rail reads nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFQ8qXgjG9CR9fxF2b
…ection row

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFQ8qXgjG9CR9fxF2b
@vercel

vercel Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

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

4 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Nov 5, 2026 1:04am UTC
flow-state-dev-kitchen-sink Ignored Ignored Nov 5, 2026 1:04am UTC
flow-state-dev-ui Ignored Ignored Preview Nov 5, 2026 1:04am UTC
flow-state-dev-build-site Skipped Skipped Nov 5, 2026 1:04am UTC

Request Review

@linear-code

linear-code Bot commented Nov 4, 2026

Copy link
Copy Markdown

FIX-2411

@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-05T01:07:51.462231Z a2fb7ac New commits
ℹ️ 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 jhoffner left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Second look + architecture notes (FIX-2411)

Overall the shape is sound: server-side include=status plus a user-topic run notice is leaner than a per-row read or polling, and useSessionList reuses useFencedRead/coalescedReads rather than inventing a driver. Findings below, ranked. None block the direction; #1 and #2 are worth fixing in this PR since it's already touching both areas.

1. "Latest request status" is now written twice (refactor opportunity)

engine/src/routes/session-request-status.ts defines its own GOING = ["in_progress","suspended"] and the "live beats most-recent, else most-recent" rule. child-session-routes.ts already has LIVE_STATUSES, isLiveWhenMostRecent, and resolveDispatchRunStatus (FIX-1010) with a comment about exactly this rule and about the two reads not being atomic. Two copies of the rule will drift (e.g. a new RequestStatus gets classified in one place only).

Suggestion: extract the "pick the governing request" step (read most-recent, else read one live) into one shared helper next to LIVE_STATUSES, and have both resolveDispatchRunStatus and latestRequestStatus call it; the wire-status mapping (TERMINAL_WIRE_STATUS) stays in child-session-routes, waitsForUser stays here.
Note the read order also differs: child-session-routes reads live first, then most-recent, specifically because of the non-atomic race (a run enqueued between reads). This new helper reads most-recent first, so it is exposed to the race the other one was written to avoid. A shared helper settles which order is right once.

2. Unbounded fan-out in handleListSessions

Promise.all(visible.map(latestRequestStatus)) issues up to 2 request reads (+1 suspension read) per visible session. If the caller passes no limit (the navigator doesn't), a user with hundreds of sessions triggers hundreds of concurrent store reads on every run notice, and the user topic now fires on every session/request write. Combined with the live refetch, that's the hot path.
Options in order of preference: (a) a batched store read (request.list for a set of sessionIds, grouped in memory), (b) a bounded concurrency map, (c) at least cap include=status rows or document the cap. I'd do (b) now, (a) as a follow-up if the store API makes it awkward.

3. Notice amplification on the user topic

Every non-delta request/session write now also publishes run to the owner's user topic, and useSessionList re-lists on every one. A single turn writes several request rows (start, status, suspension, finish), each causing a full re-list (coalesced to one in flight + one waiting, good, but each re-list is item 2's fan-out). The toOwner: false carve-out for state deltas is the right instinct; consider also deduping at publish time (skip the owner notice unless the request's status changed) so the list only refetches when a row could actually look different. Please add a test pinning which writes do/don't reach the user topic (change-bus.test covers some; confirm it covers request status writes that don't change status).

4. Hook API surface

useLiveSessionRead takes six positional args including extraIdentity, and is exported as @internal from a public hooks file only so reads.ts can import it. Two smaller smells: the useMemo with eslint-disable exhaustive-deps keyed on subscribe === undefined, and includeStatus defaulting to true in the public hook but the navigator hardcoding true. Consider an options object for the internal function and keeping it out of hooks/useSessionList.ts's public file (e.g. internal/), so the public module exports only useSessionList.

5. Nits

  • session-request-status.ts is doing a suspension read to compute waitsForUser for every suspended row; it filters by requestId in memory after listing all pending suspensions for the session. Filter at the source if the store supports requestId (BP-033).
  • client.sessions.list: include.join(",") || undefined passes an empty array as undefined; fine, but add a test for include: [].
  • Docs say "user, not person" in one commit and the code comments/changeset still say "person" in several places (SessionRowState, session-request-status.ts); pick one.
  • .changeset bumps engine/client/react as minor and the changeset text contains the issue ID FIX-2411; changesets are the allowed place for IDs, but check the apps/docs pages added in this PR don't carry any (the project's user-docs rule).

Second-look: is there a better approach?

Considered: a dedicated GET /sessions/status endpoint, or pushing status in the notice payload. Both add surface; include=status on the existing list is the leaner call and keeps the client one read. The only structurally better alternative is deriving status from a denormalized lastRequestStatus on the session record (written when a request status changes), which would make item 2 vanish entirely (zero extra reads) and make the user-topic notice meaningful by construction. That's a larger change (BP-030 dual-read for old records) and I wouldn't ask for it here, but it's worth a note on the issue if list latency shows up.


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 (FIX-2411)

Verdict: The core approach is the right one for this codebase — not over-engineered relative to the alternatives. I’m approving the direction; the notes below are simplification and follow-up, not blockers.

What would have been more complex (and why this PR is reasonable)

Alternative Why it’s worse here
Per-session subscribe in the list Topic/socket explosion as the rail grows
Client-side status per row N+1 HTTP from the browser
TanStack Query / SWR Fights useFencedRead, one-read-per-host, and client.subscribe semantics
Push row payloads on the bus New wire contract + merge logic in every host

What you shipped matches existing panel/navigator patterns: useFencedRead + coalescedReads + ReadDriver + topic.user() + full re-list. Engine-side include=status keeps the UI dumb. Suppressing user-topic run on field deltas in publish-writes.ts is the important guard against refresh storms during busy turns.

Where complexity did creep in (process + debt, not wrong architecture)

  1. PR surface area — ~2.4k lines are retained specs/POCs for FIX-2409/2411/2412 plus harness goal-driver work. The runtime change for 2411 is ~1.1k LOC and reads cleanly; the bundled artifacts make review harder than the feature warrants. If you can split spec merges from implementation in future, do — I’m not blocking on it here.

  2. Duplicate “which request wins?” logic — latestRequestStatus mirrors the two-read shape in child-session-routes.ts (resolveDispatchRunStatus / LIVE_STATUSES) with a different ordering policy. Comments warn against sharing constants, but algorithm drift is the risk (dispatch-run UI vs session-row badge disagreeing). A shared internal helper with two policies, or one cross-test matrix, would be simpler long-term than two prose-linked copies.

  3. Dogfooding gap — Framework exports useSessionList + session-row helpers, but Kitchen Sink harness rails still use harness-frame’s hand-rolled sessions.list + local HarnessSessionList labels, and Flow State still nudges the assistant leaf on title change. That’s extra moving parts while the new hook exists. Wiring harness + dropping title-driven assistantLeafRefresh once user-topic run is trusted would shrink app glue (may be intentional follow-up per spec — flagging as simplification opportunity).

  4. Scale tradeoffs (acceptable for v1 rails, document or batch later) — include=status is O(rows × store reads) per list refresh; each open navigator leaf mounts its own user-topic subscription, so K leaves ⇒ up to K list refetches per notice (coalesced per hook, not globally). Fine for tens of sessions; worth a doc limit or a follow-up batch/denormalize issue if hosts list hundreds.

Skipped (larger refactors — recommend only if product needs them)

  • Denormalize latest request status onto SessionRecord at write time (simplest reads, heavier writes)
  • Single shared user-topic driver at FlowProvider / navigator root (fewer subscriptions)
  • Merge FIX-2409 snapshot subscribe into this hook (different data shape — share a notice-filter helper instead)

Checks

Did not re-run CI locally; package tests added for listing status, bus user topic, node live-list, and useSessionList look like the right enforcers for the contract.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: faf9783009

ℹ️ 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".

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

Code Snob — already tight. A rewrite does not shrink this contract. No POC.

I read publish-writes.ts, session-request-status.ts, session-routes.ts, client.ts, types/index.ts, useSessionList.ts, reads.ts, session-row.ts, FlowNavigator.ts, and the tests in change-bus.test.ts, session-listing-status.test.ts, useSessionList.test.ts, live-session-list.test.ts, and flow-navigator.test.ts.

  • The user topic is one more notice on the identity those writes already cache. Deltas and items skip it, the recorded cut. Publishing them on the parent path would wake every open list.
  • latestRequestStatus is two bounded reads, plus one suspension read when the row is suspended. resolveDispatchRunStatus reads in the other order, treats interrupted as live only when it is the newest, and collapses to active or a terminal wire status. child-session-routes.ts already says those two live sets stay separate. A shared picker carries both policies and is longer than this function.
  • include gains the status token. The row copy adds requestStatus and, when present, requestWaitsForUser. The client joins an include array into that query.
  • liveListDriver is the panel driver plus the page-visible read and the run / resync filter. useSubscription fences nothing and does not see visibility. useLiveSessionRead is the one read useLeafSessions and useSessionList share; the leaf still passes its visit token.
  • sessionRowState is the one table plus the suspended split both rails draw from. The minute clock and the two spans are the mark and the age.
  • Each test case is one clause: a live request wins, a wait on other work is false, another owner stays out, items and deltas stay quiet on the user topic, visibility reads again, and the Node host shows create / running / failed within a second.

The file headers restate those reads. Cutting them leaves the same functions. The client page, the react page, and the two READMEs each state the contract for the reader who opens that page.

Kitchen Sink stays the follow-up this PR split off.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@github-actions

github-actions Bot commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

Mechanism check (advisory, never blocks)

Rows from docs/mechanisms/mechanisms.yaml · labels: none

New export Package Mechanism
sessionLabel @flow-state-dev/react react
sessionRowState @flow-state-dev/react react
sessionAge @flow-state-dev/react react
useSessionList @flow-state-dev/react react

…ads, internal live read (FIX-2411)

Review of #4749:
- engine: the session listing's include=status and the dispatch-run
  listing pick a session's governing request through one helper,
  governingRequest (live first, then most recent), so the rule and its
  read order are written once.
- engine: status reads run eight sessions at a time (mapBounded), so a
  long unlimited listing is not a burst of store reads.
- engine: the user-topic test pins that a request write with an unchanged
  status is still heard.
- react: the shared live read moves to internal/useLiveSessionRead with an
  options object; the public hook file exports only useSessionList.
- client: a test for include as a list, and for include: [].
- wording: user, not person, for the signed-in user.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFQ8qXgjG9CR9fxF2b

jhoffner commented Nov 4, 2026

Copy link
Copy Markdown
Collaborator Author

Thanks for the second look. Commit 2249c88 addresses it as follows.

1. Two copies of "latest request status": fixed.
There is now a single helper, governingRequest(store, filter), in child-session-routes.ts next to LIVE_STATUSES. It reads a live request first and falls back to the most recent one, which is the dispatch-run listing's order. resolveDispatchRunStatus and latestRequestStatus both call it. The wire mapping stays in child-session-routes and waitsForUser stays in session-request-status.ts. The helper's doc covers why live-first is the safe order when the two reads aren't atomic. The run listing, active-runs and include=status tests pass unchanged.

2. Unbounded fan-out: fixed with option (b).
include=status now reads at most 8 sessions at a time through a new utils/map-bounded.ts, with its own test. I didn't do a batched read (option a) here. The per-session request scope (owner, org, flow kind and instance) makes one batched read awkward, so I'd raise it with the denormalized lastRequestStatus you mentioned if list latency shows up.

3. Notice amplification: test added, dedupe not done.
change-bus.test now also pins that a request write whose status didn't change still reaches the user topic. I kept that behaviour on purpose. A row's state also depends on the stop's suspension record (waitsForUser). If the notice only fired when the status changed, a stop whose suspension record lands after its status write could leave the row stuck on "Waiting" instead of "Waiting on you". Re-lists are already coalesced (one in flight, one waiting) and bounded per item 2. If you want the dedupe anyway, it needs the suspension write to publish too, which I'd do as a follow-up.

4. Hook API surface: fixed.
The live read moved to src/internal/useLiveSessionRead.ts and takes an options object, so hooks/useSessionList.ts exports only the public hook and its types. The eslint-disable is gone: the memo now depends on [source, canSubscribe]. includeStatus defaults to true in both places.

5. Nits:

  • Filter suspensions by requestId at the source: not done. SuspensionFilter has no requestId, and adding one touches every store adapter. The read is already filtered by session, owner and pending, so it's a handful of rows. I've noted that in the code.
  • include: []: a client test now covers it, plus a string and a list.
  • "person" vs "user": now "user" throughout this PR's code comments, tests, READMEs and docs.
  • Issue IDs in apps/docs: none in the pages this PR touches.

Engine (4372 passed), client, react (559) and the over-push goal test (2/2) all pass. Typecheck is clean.


Generated by Claude Code

enabled joins the live read's identity, as useFencedRead asks of a caller
that toggles it, so turning it off drops held rows and any read in flight.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFQ8qXgjG9CR9fxF2b
The harness rail reads through useSessionList and draws each row's
turn state, model and age; its own read and reads counter go. The Flow
State page drops its hand re-reads; railSessions passes subscribe
through and gives coordinator rows their state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFQ8qXgjG9CR9fxF2b
The state mark and the age are drawn but aria-hidden; the row's button
carries the state as aria-description. Otherwise the age and the mark's
label joined the button's accessible name ("support.helpnow"), and a row
could no longer be found by its session's name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFQ8qXgjG9CR9fxF2b
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFQ8qXgjG9CR9fxF2b

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ab0dd12b05

ℹ️ 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".

The live driver starts only while the list is enabled, so a closed
navigator leaf holds no user-topic subscription, timer or visibility
listener, and closing the last one lets the push connection go.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFQ8qXgjG9CR9fxF2b

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 47ac0ba4f8

ℹ️ 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".

… provider (FIX-2411)

runAction writes stops through runtimeConfig.durabilityProvider, so the
status include reads them there too, falling back to the suspension store
the default provider writes to. A host with its own suspension storage no
longer shows its questions as "Waiting".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFQ8qXgjG9CR9fxF2b
…(FIX-2411)

The router options type has no top-level durabilityProvider, so CI typecheck
failed even though vitest passed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFQ8qXgjG9CR9fxF2b
…read is bounded (FIX-2411)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiE3DUKgZCYa7rK37qK
…ns, never the flow whole (FIX-2411)

The rail's coordinator status read listed the whole coordinator flow,
which reads every coordinator's sessions and broke the shell's
reading-only-leaves check. Each declared coordinator now lists its own
sessions (state.workerId) with status.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiE3DUKgZCYa7rK37qK
@jhoffner
jhoffner added this pull request to the merge queue Nov 5, 2026
Merged via the queue into main with commit 62b40d3 Nov 5, 2026
14 of 15 checks passed
@jhoffner
jhoffner deleted the claude/project-thread-i8owvt branch November 5, 2026 01:14

jhoffner commented Nov 5, 2026

Copy link
Copy Markdown
Collaborator Author

Test (3/3) failed on a2fb7ac in labs/teammates/test/screen.test.tsx:382. The test waits for the popup to say "Starting on Cursor…", but the fake run finished first and the popup already read "Started on Cursor". That's a timing race in the test, not something this PR changed. The merge from #4760 touches only apps/kitchen-sink, and the same test passed on 924828c. Locally it passes 3 out of 3 runs (37/37 each time). I'll re-run the failed job once the workflow finishes.


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants