Repository navigation
feat(engine,client,react): live session list with each row's state (FIX-2411) - #4749
Conversation
…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
|
The latest updates on your projects. Learn more about Vercel for GitHub. 4 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. |
jhoffner
left a comment
There was a problem hiding this comment.
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.tsis doing a suspension read to computewaitsForUserfor every suspended row; it filters byrequestIdin memory after listing all pending suspensions for the session. Filter at the source if the store supportsrequestId(BP-033).client.sessions.list:include.join(",") || undefinedpasses an empty array asundefined; fine, but add a test forinclude: [].- 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. .changesetbumps engine/client/react asminorand the changeset text contains the issue IDFIX-2411; changesets are the allowed place for IDs, but check theapps/docspages 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
There was a problem hiding this comment.
/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)
-
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.
-
Duplicate “which request wins?” logic —
latestRequestStatusmirrors the two-read shape inchild-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. -
Dogfooding gap — Framework exports
useSessionList+session-rowhelpers, but Kitchen Sink harness rails still useharness-frame’s hand-rolledsessions.list+ localHarnessSessionListlabels, 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-drivenassistantLeafRefreshonce user-topicrunis trusted would shrink app glue (may be intentional follow-up per spec — flagging as simplification opportunity). -
Scale tradeoffs (acceptable for v1 rails, document or batch later) —
include=statusis 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
SessionRecordat 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.
Sent by Cursor Automation: Review For Best Approach
There was a problem hiding this comment.
💡 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".
There was a problem hiding this comment.
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.
latestRequestStatusis two bounded reads, plus one suspension read when the row issuspended.resolveDispatchRunStatusreads in the other order, treatsinterruptedas live only when it is the newest, and collapses toactiveor a terminal wire status.child-session-routes.tsalready says those two live sets stay separate. A shared picker carries both policies and is longer than this function.includegains thestatustoken. The row copy addsrequestStatusand, when present,requestWaitsForUser. The client joins an include array into that query.liveListDriveris the panel driver plus the page-visible read and therun/resyncfilter.useSubscriptionfences nothing and does not see visibility.useLiveSessionReadis the one readuseLeafSessionsanduseSessionListshare; the leaf still passes its visit token.sessionRowStateis 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.
Sent by Cursor Automation: Code Snob
Mechanism check (advisory, never blocks)Rows from
|
…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
|
Thanks for the second look. Commit 2249c88 addresses it as follows. 1. Two copies of "latest request status": fixed. 2. Unbounded fan-out: fixed with option (b). 3. Notice amplification: test added, dedupe not done. 4. Hook API surface: fixed. 5. Nits:
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
There was a problem hiding this comment.
💡 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
There was a problem hiding this comment.
💡 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
|
Test (3/3) failed on a2fb7ac in Generated by Claude Code |


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.runnotice on the owner's user topic.GET /sessions?include=statusaddsrequestStatusto each row.requestWaitsForUser. A question or approval counts astrue; a wait on other work counts asfalse.sessions.list({ include: ["status"] }).SessionSummarygainsrequestStatusandrequestWaitsForUser.useSessionListhook. It re-reads on arunnotice and when the page becomes visible.FlowNavigatorleaves read through it, so they are live.sessionLabel,sessionRowStateandsessionAgeare exported.api/client,api/react,workforce/uiandguides/realtime.How it was verified
packages/node/test/live-session-list.test.ts(two clients on a served port)in_progress,completedandfailedeach within 1 s. Another user's watcher reads nothing.publish-writes.ts, test 1 fails with "not within 1000 ms".change-bus.test.tssession-listing-status.test.tssuspended, true. A wait givessuspended, false. A completed session givescompleted.useSessionList.test.ts(7 tests)runnotice, not onitems. Also reads on visibility. Withoutsubscribeit reads once. It closes on unmount. Red state produced.Kitchen Sink under Next serves no push socket (
/capabilitiesreturnspush: 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