Skip to content

spec(FIX-2411): live session list with per-row status, model and recency - #4728

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

jhoffner merged 4 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

Someone who… Today After
runs several coding sessions in a Kitchen Sink harness mode Each row shows only a title or an id. A failed, interrupted or waiting turn looks the same as a finished turn Each row shows the state of its latest turn, its model and its age. Rows that need you have a mark. A row changes in less than 1 s
starts a session in another tab, or from a script The session does not show until you reload The session shows in less than 1 s (D1)
starts a session with fsdev run on the local SQLite store The session does not show until you reload The session shows when you come back to the tab. On the Postgres bus, in less than 1 s
works in Flow State mode An open rail section reads its sessions one time. The page reads it again by hand The open section is live and has the same marks. The hand reads go
builds an app with a list of sessions Writes a read and its own triggers Calls useSessionList. The rows are live and each has its state (D2)

Goal: in each Kitchen Sink mode, the session rail shows a new session from anywhere on the server, and the latest turn state of each row, in less than 1 s, with no reload and no timer while push is up. A session from another process shows when the tab becomes visible again.

flowchart LR
  A["Kitchen Sink · test mode · scripted Claude Code"] --> L1["leg a · a second client creates a session"]
  A --> L2["leg b · another tab runs a slow turn, then a failing one"]
  A --> L3["leg c · a session no notice names · the tab is hidden, then shown"]
  L1 --> T["what the watching tab's rail shows · and how often it reads"]
  L2 --> T
  L3 --> T
  T -->|"a, b within 1 s, no reload · b no read per item · c on show"| P["PASS · goal met"]
  C["controls · no-user-notice · no-show-read"] -.-> L1
  T -.->|"under a control"| F["must FAIL"]
Loading

The check reads what the rail shows and counts listing reads. Check: a Kitchen Sink browser test (legs a, b) and a react test (leg c). Controls that must fail: GOAL_CONTROL=no-user-notice (legs a, b), GOAL_CONTROL=no-show-read (leg c).

What changes: the bus publishes run on the owner's user topic; the listing returns each row's latest request status; useSessionList is the live public read under FlowNavigator and the Kitchen Sink harness rail; the frame's own read and the page's hand re-reads go

The bus already tells when a session changes. This change adds the one topic that a list watches, the state that a row needs, and one hook that both rails use.

How: the bus also publishes run on the user topic of the session owner. The listing returns the latest request status of each row when you ask for it. The navigator's leaf read becomes live and public.

Sign off

The goal, at that size. If wrong: the rail shows new sessions but cannot show which run needs you.

The debt: net down. One read and its counter, two hand re-reads and a duplicate helper go. One hook comes in. If wrong: two list hooks in react drift apart.

Your user topic hears every change to your sessions · D1

Chosen: the owner's user topic hears every change. Instead of: each listed session's own topic. Decides it: rows not listed yet. Price: a listing read when any of your sessions starts or ends a turn

It comes down to rows that are not listed yet: the topic of one session cannot tell about a different session. This is the one to weigh: it reverses FIX-2466 D1, by its own flip condition. If wrong: a user with many busy sessions makes each open rail read often.

One live read under both rails; the harness rail keeps its flat drawing · D2

Chosen: one live read, each rail keeps its drawing. Instead of: the harness rail as a FlowNavigator. Decides it: the navigator opens flows as kind rows. Price: two drawings of one row

It comes down to the navigator's shape: in a harness mode it adds a kind row to open first. If wrong: two drawings of one row drift apart.

The pull-request badge waits for a follow-up (FIX-2553) · D3

Chosen: a follow-up adds the badge. Instead of: a badge on every row now. Decides it: reads, one more per row per change. Price: open a session to see its pull request

It comes down to reads: a badge costs one read per row. The state costs none past the listing. If wrong: you open a session to see its pull request.

Open: none. Reasons and what lost: DECISIONS.md.

Analysis: right approach, run by the author (no fresh sub-agent). DECISIONS.md → Analysis.

Reviewers · look here

  • Decisions → D1. Is a listing read for each turn start or end of any of your sessions an acceptable cost for one topic that covers all rows?
  • Decisions → decided, not asked. The tab becoming visible starts one read. This covers fsdev run on SQLite, where the in-memory bus says that it crosses processes. Does this go against FIX-2369 D2?
  • Spec → what's already here. useSessionList is a second public list hook beside useFlow. Is "extends useLeafSessions" correct?

Not here: the claude-code-style lab's list (FIX-2552), the pull-request badge (FIX-2553), navigator leaf events (FIX-1494).

Spec · Decisions · Linear FIX-2411 · epic FIX-2369 · builds on FIX-2426, FIX-2428 · amends FIX-2426's publish table, supersedes part of FIX-2466 D1 · merges after human approval and required checks

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.


Generated by Claude Code

@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 10:18pm UTC
3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Nov 4, 2026 10:18pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Nov 4, 2026 10:18pm UTC
flow-state-dev-ui Ignored Ignored Preview Nov 4, 2026 10:18pm UTC

Request Review

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

FIX-2411

@jhoffner jhoffner assigned jhoffner and unassigned Copilot Nov 4, 2026
@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-04T22:19:20.307665Z 8880af9 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 4, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (FIX-2411 spec)

Checked the spec against packages/engine/src/bus/publish-writes.ts, in-memory-bus.ts, push/socket-session.ts and flow-navigator/reads.ts. The direction holds: a user-topic parent, listing-side status, and one hook under both rails is the leaner shape than per-row topics or browser-side status. Four findings below. 1 and 2 can change the approach; 3 and 4 are for the implementer.

1. D1's cost can be cut now, at the publisher, instead of waiting for its flip (direction)

D1 publishes run on the user topic for "every session write and every request write except items". Read against the code, that is wider than the rail needs:

  • requestWrites publishes request for every request write, including the delta verbs (patchField, incField, pushToArray). The rail's state only moves when the request's status moves (set/setFieldsIfStatus into a new status, delete). If any per-turn counter or field uses a delta verb, every one of them wakes every open rail.
  • sessionNotices already fires for child run sessions (parentSessionId). Whether the listing returns those rows is a spec question the spec never answers. If it doesn't list them, their writes are wasted wakes. If it does, say so.

D1's flip is "tens of sessions running turns at once". Gating the user-topic notice on status-changing request writes + session create/delete/title/state writes is a small predicate in the one publisher. It makes the accepted price smaller up front and doesn't add a kind or a topic. Suggest D1 lock in the narrower rule, or state why the wide one is needed.

2. The publisher doesn't have the owner today (direction, small)

Identities caches { id, tenantId, parentSessionId } only. The "owner is one more parent" framing in D1 ("reuses the bus's one rule, no new kind or topic") undersells the change: the owner must be added to the identity cache and to the request path (requestNotices already does a cached session read, so that part is cheap). Note it in "Locks in" so the implementer doesn't discover it as a surprise. Also: a user topic already carries resource_change notices for user-scoped resources, so the hook must filter on kind === "run" (a resource-narrowed subscriber won't hear a run at all). Worth one line.

3. One home for "needs you" (architecture, for D2)

D2 accepts two drawings of one row. The part that should not be drawn twice is the rule: suspended | interrupted | failed | incomplete needs you, aborted doesn't, and the label/recency derivation. Today that rule lives only in "Decided, not asked" prose. Have useSessionList return rows already carrying needsYou (and the shared label helper), so the harness list and the navigator draw from the same derived row and cannot disagree. That removes most of D2's "drift" risk without the navigator changing shape.

4. Don't copy the status rule (for the implementer)

"Builds on resolveDispatchRunStatus / resolveActiveDispatchRuns" while "keeping suspended and interrupted apart" reads like a second near-copy of the same rule. Extract the shared selection (live request wins, else most recent) and let the two callers differ only in how they collapse the status. Otherwise the debt line ("net down") quietly gains a duplicate.

Not raised

The visibility-read workaround for fsdev run on SQLite is a patch over the in-memory bus reporting crossesProcesses: true for a two-process setup. It is acceptable here and already recorded as a leave; no change requested.


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

Direction looks right: reuse change-bus parent propagation, batched include: "status" on the listing, and useSubscription coalescing is a cleaner net than today's harness reads counter, Flow State hand leaf.refresh() calls, and the claude-code-style lab's per-row subscription pump. Deferring D3 and FIX-2552 is appropriate scope control.

I do not think the spec over-built relative to the goal. The main complexity is inherent (hear unlisted sessions and row status without N+1 or per-item reads). The rejected alternatives in DECISIONS match what the codebase already does (watchSessions, FIX-2466 reload-only, focus-only refresh).

Where the approach is as simple as it gets

  • D1 (user-topic run) vs per-row topics + create-only notices: the parent-chain extension is the smallest bus change that satisfies leg (a) and (b) with one subscription. FIX-2466's flip is acknowledged with a concrete escape hatch.
  • include: "status" on the listing vs browser-side request reads: aligns with ER-5 and existing resolveDispatchRunStatus work.
  • Two PRs (packages, then Kitchen Sink): keeps review and rollback sane.

Simpler shapes worth considering (non-blocking)

  1. Public hook vs component — packages/react/.../reads.ts deliberately keeps leaf reads internal to avoid a third public list entry point that could multiply flow-list reads. This spec adds a second public list API beside useFlow. That trade is documented, but at implementation time I'd keep useSessionList as thin as possible (literally useFencedRead + useSubscription on topic.user(), shared with useLeafSessions via one internal helper). If the only out-of-navigator consumer for a while is Kitchen Sink, an exported sessionLabel helper + documented hook pattern might have been enough for v1 — I'm not sure the public hook is premature; D2's builds-an-app row argues for export. Flagging for the gate, not requesting a spec rewrite.

  2. D2 row duplication — Two flat row renderers (navigator vs HarnessSessionList) over one read is honest debt. To reduce drift without merging rails: export sessionLabel (and maybe a tiny SessionStatusMark presentational component) from @flow-state-dev/react when deduping ENGINE_ID, instead of only deduping the regex in one package file.

  3. Coordinator / railSessions path (DECISIONS decided, not asked) — Flow State keeps a second, narrowed listing shape for coordinator rows. That's real app complexity. Worth a one-line implementer note so the page doesn't grow a third read pattern.

  4. useLeafSessions open-gate vs harness always-on — Spec should make explicit in the package PR that useSessionList is always enabled while mounted (harness rail), while the navigator continues to gate on leaf open via the existing hook internally. Otherwise implementers may accidentally reuse the closed-leaf enabled: false semantics.

  5. Analysis — The embedded analysis is self-authored. Fine for draft; I'd still run the analysis skill once before direction approval since D1 reverses FIX-2466 and adds a permanent second react list hook.

Performance (acceptable with eyes open)

  • D1 means any turn on any of the user's sessions triggers a coalesced listing read for every open rail — correct for Kitchen Sink scale; the documented flip is the right pressure valve.
  • Leg (b) anti-game should reuse the rule that items does not publish on the user topic — worth an explicit implementer test.

Skipped (larger refactors)

  • Flat single-flow FlowNavigator mode (D2 rejected alternative): FIX-1494 long-term path.
  • Third-party library: no fit; framework owns bus + listing contracts.

Verdict: Approve the spec direction. Implementation should stay minimal — compose existing pieces, don't grow watchSessions-style pump state in react.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2411/SPEC.md Resolved
Comment thread specs/issues/FIX-2411/SPEC.md Resolved
Comment thread specs/issues/FIX-2411/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2411/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2411/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2411/DECISIONS.md Resolved

@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: fcde389523

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

Comment thread specs/issues/FIX-2411/DECISIONS.md Resolved
The rows' request scopes differ, so the runs listing's batched read
doesn't carry over; the listing reads at most two one-record reads per
row on the server.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFQ8qXgjG9CR9fxF2b
The user topic skips state field deltas, and a stop on other work is
not waiting on you (requestWaitsForUser). Other review points recorded
for the implementer.

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

Review round 1 is folded in cc5885a.

  • Second look 1 (D1's cost): folded. The user topic now skips state-field deltas (patchField, incField, pushToArray, deleteField), which a busy turn writes many of. Set, status writes and deletes still publish. Child-run sessions do reach the user topic, but the listing shows them only with include: "dispatch-runs". One coalesced read per burst covers the case where they aren't listed.
  • Second look 2: the owner goes into the bus's session identity (D1 → Locks in now says so). The hook reads again only on run, resync or a reconnect, so a resource notice on the user topic doesn't wake it.
  • Second look 3 and 4, and the six Cursor notes: recorded verbatim in DECISIONS → Notes from review for the implementer.
  • Codex (automatic waits): folded. Answered on its thread.

Generated by Claude Code

…ink bounded by its timer

Kitchen Sink under Next serves no push socket, so its rail reads on the
client's 3 s fallback timer. The one-second bound is proven where push is
up; Kitchen Sink's browser test is bounded at 4 s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiFQ8qXgjG9CR9fxF2b
@jhoffner
jhoffner added this pull request to the merge queue Nov 4, 2026
Merged via the queue into main with commit db2c15a Nov 4, 2026
20 checks passed
@jhoffner
jhoffner deleted the claude/project-thread-i8owvt branch November 4, 2026 23:10
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