Skip to content

feat(kitchen-sink): live session rails with each row's state (FIX-2411) - #4760

Merged
jhoffner merged 4 commits into
claude/project-thread-i8owvtfrom
claude/project-thread-vhnnhd
Nov 5, 2026
Merged

jhoffner merged 4 commits into
claude/project-thread-i8owvtfrom
claude/project-thread-vhnnhd

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 5, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

What this does

The Kitchen Sink half of FIX-2411 (spec specs/issues/FIX-2411/, #4728). Stacked on the package PR #4749; GitHub retargets it to main once #4749 merges. Merge #4749 first.

  • Claude Code / Codex / Cursor rail: reads through useSessionList, so a session started in another tab joins the rail without a reload, and each row shows its turn state (Running, Failed, ...), model and age. Its own one-off read and reads counter are gone.
  • Flow State page: the hand re-reads (after "New session" and after a title arrives) are gone; the open leaf hears the user's change notices instead.
  • railSessions: passes subscribe through so the navigator's leaves stay live, and gives coordinator rows their turn state from the coordinator flow's own status listing.

Kitchen Sink under Next serves no push socket, so its rails refresh on the client's 3 s fallback timer. The new e2e is bounded at 4 s for that reason; the 1 s goal over real push is proven on the Node host in #4749.

What's asked of you

Review and merge after #4749. No changeset: the app is private.

Worth a close look

  • lib/rail-sessions.ts: the coordinator status read runs only when the navigator asks for include: ["status"], lists each declared coordinator's own sessions (state.workerId), never the coordinator flow whole (the shell's reading-only-leaves e2e holds that), and a row keeps its coordinator-id title.

Verification

Check Result
New e2e e2e/live-session-list.spec.ts (2 cases) Pass.
Negative control: same spec with the app code reverted to #4749's (app/, components/, lib/ from the base), rebuilt Both cases fail: the other tab's session never appears in the rail within 4 s.
Kitchen Sink unit tests 462 passed, 2 skipped (incl. new rail-sessions.test.ts and harness-mode.test.tsx cases). The per-coordinator listing case fails on the earlier whole-flow read.
pnpm typecheck (kitchen-sink) Clean.
e2e after merging #4749's row-name fix workforce-shell, address, talk-from-page, live-session-list: 22 passed. (Locally the container's newer Chromium also logs a /favicon.ico 404 that trips the console-error fixture; with a stub favicon, not committed, that noise goes away. CI's browser is unaffected.)

Fixes FIX-2411 (Kitchen Sink half).

https://claude.ai/code/session_01NczDiE3DUKgZCYa7rK37qK


Generated by Claude Code

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

vercel Bot commented Nov 5, 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 12:39am UTC
flow-state-dev-kitchen-sink Ignored Ignored Nov 5, 2026 12:39am UTC
flow-state-dev-ui Ignored Ignored Preview Nov 5, 2026 12:39am UTC
flow-state-dev-build-site Skipped Skipped Nov 5, 2026 12:39am UTC

Request Review

@linear-code

linear-code Bot commented Nov 5, 2026

Copy link
Copy Markdown

FIX-2411

@jhoffner jhoffner assigned jhoffner and unassigned Copilot Nov 5, 2026
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 5, 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-05T00:40:32.928736Z 3a166e9 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 commented Nov 5, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture review

Overall: the direction is right. Moving the harness rail and Flow State page onto useSessionList and deleting the hand re-read plumbing (refreshSessions, onTitled, assistantLeafRefresh, reads counter) is a real simplification. Findings below, ranked. Nothing blocking apart from #1, which is worth deciding before merge.

1. HarnessSessionList re-implements the navigator's row (duplication, worth fixing here)

components/harness-session-list.tsx now has its own useMinuteClock (a copy of the private one at packages/react/src/components/flow-navigator/FlowNavigator.ts:195) and its own mark / label / age markup around sessionRowState, sessionLabel, sessionAge. This is the second consumer of that row anatomy, so the next change to the row (new state, a11y tweak) has to be made twice. Per CLAUDE.md "common helpers belong in a shared place, no duplicate copies":

2. sessionModel reads state.model through an as cast

(session as { state?: { model?: unknown } }).state?.model relies on the listing carrying state without that being in the SessionSummary type. If the server stops projecting it (or projects only exposed fields), models silently disappear from every row and the only test that would notice is the new unit test with a hand-built fake. Either confirm SessionSummary types this field (then drop the cast) or add one assertion against the real listing shape (e.g. in the new e2e: the row shows the model label). Right now the e2e doesn't check the model at all, only the unit test does.

3. rows derivation hides a state

In harness-frame.tsx:

const rows = (list.isLoading || listError !== null) && list.sessions.length === 0 ? null : list.sessions;

null conflates "loading" and "failed". It works because listError is checked separately, but the fold also means a refresh that starts while the list is empty (e.g. last session deleted elsewhere) flips back to null, and the address-resolution effect keyed on rows re-fires its "not found" logic path. A one-line comment is there; consider returning list.sessions plus an explicit ready flag (!list.isLoading || list.sessions.length > 0) so the effect depends on the flag rather than on null-ness. Low risk, small change.

4. railSessions makes a second full coordinator listing per navigator read

When include: ["status"] is set, every rail read now does ensureWorkerSession per coordinator and a whole sessions.list({ flowKind: "coordinator" }), matched back by id. That's a fine trade for a demo app, but note:

  • the second list isn't scoped by userId explicitly (relies on the client default; the old frame code passed KITCHEN_SINK_USER_ID). Worth a one-line confirmation that client.userId is applied.
  • if ensureWorkerSession can return the summary with status already (it returns a SessionSummary), asking the workforce client for status would remove the join entirely. If that's a workforce gap, it belongs as a follow-up on the package side, not another app-level adapter. This is the app compensating for a package gap, which apps/kitchen-sink/CLAUDE.md says to surface.

5. Test coverage notes

  • The e2e's second case uses a 10 s timeout on the failed mark but LIVE (4 s) elsewhere; fine, but the [slow] -> toHaveCount(0) step is a negative assertion that passes trivially if the mark never rendered. The preceding in_progress assertion covers that, so OK.
  • Negative control (reverting to feat(engine,client,react): live session list with each row's state (FIX-2411) #4749's app code) is good evidence for the e2e. No concerns.

Not for this PR

  • The 7 red E2E specs are from the accessible-name change in feat(engine,client,react): live session list with each row's state (FIX-2411) #4749 (support.helpnow). Agree it belongs there; when fixing, prefer giving the row button an aria-label of just the label (or moving age/mark outside the button's name) so getByRole("button", { name: "support.help", exact: true }) keeps working, rather than loosening the 7 specs.

Net: land after #4749, ideally folding #1 (shared clock/row helper) first; #2 and #4 are cheap confirmations.


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 harness / Flow State rails)

Verdict: The direction is right and worth merging. Swapping the harness frame to useSessionList, deleting the reads counter / onTitled / leaf.refresh() chains, and passing subscribe through railSessions is the simpler architecture: one live read path, notices instead of imperative “please re-list.” That is the big win.

Where complexity crept in anyway: most of it is presentation, not the live-list wiring.

  1. HarnessSessionList re-implements FlowNavigator row chrome — status mark, age, data-* hooks, and a copy of useMinuteClock already live in FlowNavigator.ts. You correctly reused sessionLabel / sessionRowState / sessionAge from @flow-state-dev/react; the remaining JSX is the drift surface (Tailwind orange vs nav CSS vars, missing full-date title on age, etc.). Kitchen Sink’s own rule says a second rail host is the signal to lift shared UI into the framework. Cleaner follow-up (not a blocker): export a small SessionRowMeta + shared useMinuteClock (even @internal) and keep harness-only the model subline.

  2. rail-sessions status merge — reasonable glue for coordinator rows built via ensureWorkerSession. When include has "status", you pay ensureWorkerSession × N plus a full coordinator list with status. Fine for three coordinators; worth a one-line comment that this is intentional and bounded, or a follow-up to fold status into the workforce read if this pattern spreads.

  3. Stale module doc — harness-session-list.tsx still says the frame “reads the listing once,” which contradicts harness-frame.tsx and the new behavior. Easy fix before or right after merge.

  4. sessionModel cast — if listing already exposes readonly state for harness flows, typing that on SessionSummary (or a narrow listed-session type) removes the cast; optional polish.

  5. rows tri-state in harness-frame — (loading || error) && sessions.length === 0 ? null : sessions re-encodes hook semantics. Not wrong; could shrink later by passing list through or a tiny { rows, phase } helper if this pattern repeats.

Performance (scoped to this diff): default includeStatus: true + 3s poll in Next (no push) means periodic full list+status work — acceptable for harness-scale rails; the new e2e documents the bound well. Coordinator double-list is the only local smell.

Skipped (larger refactors): mounting FlowNavigator on harness pages (wrong UX), moving coordinator status into workforce in this PR.

Approving because the live-list approach is the right default and the remaining items are follow-up simplification, not a wrong architecture.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

@@ -8,22 +8,35 @@
* row that opens closed. Here the sessions are the rail's content. Drawn from
* the rows the frame read, so the frame reads the listing once. A failed read

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.

This header still says the frame reads the listing once (Drawn from the rows the frame read…). After useSessionList in harness-frame, that is misleading for the next reader. Worth aligning with the frame module doc (live notices / poll fallback).

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.

Fixed in 359240e: the header now says the rows come from the frame's live read (notices, or the fallback timer without push).


Generated by Claude Code

const match = ENGINE_ID.exec(session.id);
return match === null ? session.id : `${match[1]}_…${match[2]!.slice(-6)}`;
/** Now, a minute at a time: ages are drawn in minutes, never re-read. */
function useMinuteClock(): number {

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 / reuse: useMinuteClock is duplicated verbatim from private code in FlowNavigator.ts. Not introduced by the live-list wiring itself — if we keep enriching flat rails, exporting this hook (or bundling it with shared row meta) avoids a third copy when another host appears.

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.

Kept as is for this PR. The navigator's clock is private to @flow-state-dev/react, so exporting it (or a shared row-meta component) is a package change that belongs in #4749 or a follow-up, not in the app PR.


Generated by Claude Code

>
{sessionLabel(session)}
<span className="flex items-center gap-1.5">
{state !== null && (

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 / reuse: This mark + age layout mirrors sessionMeta() in FlowNavigator. Helpers are shared (session-row.ts); markup is not yet. Medium-term cleaner shape: a framework SessionRowMeta (className overrides for harness vs navigator) and harness-only second line for model. Optional for this PR, but this is the main “went further than necessary” surface area.

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.

Same as the clock: the shared helpers (label, state, age) are reused; lifting the markup into a framework component is a package change. Leaving it for a follow-up so this PR stays app-only.


Generated by Claude Code

/** An engine-minted session id: its prefix, a timestamp, and a hex tail. */
const ENGINE_ID = /^([a-z]+)_\d{13}_([0-9a-f]{6,})$/;
/** The model a listed session was born with: a readonly state field the listing carries. */
function sessionModel(session: SessionSummary): string | undefined {

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.

Cast on state.model — if the listing contract already carries exposed readonly session state for harness kinds, a typed field on SessionSummary (or a narrow list row type) would drop this helper entirely. Uncertain whether client types already guarantee state on list responses everywhere; if yes, typing beats casting.

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.

Leaving the cast: SessionSummary doesn't type a per-flow state field, and typing it for harness kinds is a client contract change outside this app PR.


Generated by Claude Code

const list = useSessionList({ flowKind, client });
const listError = list.error;
// `null` until a read answers with rows: still loading, or failed.
const rows = (list.isLoading || listError !== null) && list.sessions.length === 0 ? null : list.sessions;

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.

The rows === null loading sentinel duplicates list.isLoading / list.error / list.sessions. Works today; if this tri-state shows up again, consider deriving it once next to useSessionList or exposing a small helper from react so hosts do not re-invent null-vs-empty semantics.

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.

Leaving it: the null sentinel is what the list component reads to tell loading from an empty list, and this is the only host doing it. Worth lifting if a second host repeats it.


Generated by Claude Code

Comment thread apps/kitchen-sink/lib/rail-sessions.ts Outdated
title: worker,
}),
const include = options?.include === undefined ? [] : [options.include].flat();
const [rows, listed] = await Promise.all([

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 status is included, this does workforce ensureWorkerSession for each coordinator and a separate sessions.list({ include: ['status'] }), then merges by id. Correct for marks on synthetic rows; slightly chatty. A short comment that N is bounded (SHELL_COORDINATORS) would help, or a follow-up to attach status in one workforce call if this merge grows.

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.

Added a comment in 359240e saying the find is per declared coordinator (a fixed, small set) plus one status listing when state is asked for. Folding status into one workforce call is out of scope here.


Generated by Claude Code

* timer, not push's second. The second-scale path over a real socket is the
* Node host's goal check (`packages/node/test/live-session-list.test.ts`).
*
* Red state: on the code before this change the harness rail read once, so

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.

Nit: the “Red state: on the code before…” paragraph is useful in PR narrative but reads like implementation history in a test file. Consider trimming to the bound you assert (3s poll, Node test owns push) — optional, not blocking.

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.

Leaving it: this repo's tests state their red state so a reader knows what the test catches (BP-003).


Generated by Claude Code

…read is bounded (FIX-2411)

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

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

Head fe61592ee591a5921477f6035e854ea5bd180f02. Nine files, +297/−105, all under apps/kitchen-sink.

I read harness-frame.tsx, harness-session-list.tsx, harness-mode-view.tsx, harness-session.tsx, app/flow-state/page.tsx, lib/rail-sessions.ts, e2e/live-session-list.spec.ts, test/harness-mode.test.tsx, and test/rail-sessions.test.ts. I compared them with session-row.ts, FlowNavigator.ts (sessionMeta, useMinuteClock), useSessionList.ts, client-session.ts, and SessionSummary.

  • The hand re-reads are already gone: the title effect, onTitled, the reads counter, and leaf.refresh() after New session. What remains is useSessionList.
  • D2 keeps two drawings. sessionMeta is the navigator's spans, coloured with --fsd-nav-*. The harness row is that mark, label, and age, plus the model line. A shared chrome component is a third surface and a style prop, longer than the row.
  • useMinuteClock is the same seven-line clock in each drawing. Exporting the navigator's copy adds a public hook. Moving it into session-row.ts pulls React into that pure module. The local copy stays.
  • sessionModel is the cast. SessionSummary has no state; toClientSession still sends the exposed fields, and model is one of them. Inlining the cast is the same check inside the map. Adding state to SessionSummary belongs on the listing type and does not shorten this row.
  • railSessions lists coordinator status only when include contains "status", joins by id, and keeps the coordinator id as the title. The omit-when-absent copy of requestWaitsForUser matches the listing row. subscribe is the pass-through the navigator's leaves need. Dropping the undefined guard on include is one expression of the same check.
  • The null rows value is the loading and failed-empty state the list already drew, and the address effect reads that same value. Passing isLoading beside it repeats the condition.
  • rail-sessions.test.ts is three clauses. The harness case is one live row. The e2e is the two timer cases. openMode, newSession, and send serve both cases. The other mode specs' helpers return void and do not read the session id.

The file headers restate the live read. Cutting them leaves the same functions.

The seven red Kitchen Sink e2e specs stay on #4749, where this PR left them.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

…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 merged commit a2fb7ac into claude/project-thread-i8owvt Nov 5, 2026
18 of 19 checks passed
@jhoffner
jhoffner deleted the claude/project-thread-vhnnhd branch November 5, 2026 01:04
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