Skip to content

feat(workforce): list a person's conversations with one worker (FIX-2158) - #3814

Merged
jhoffner merged 7 commits into
mainfrom
claude/project-thread-bvewrx
Oct 24, 2026
Merged

jhoffner merged 7 commits into
mainfrom
claude/project-thread-bvewrx

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

The problem. An app where a person has many sessions with one main worker (the Claude Code-style lab) cannot list them from the workforce client. findWorkerSession returns only the default conversation.

What this does. It adds one read, listWorkerSessions(worker), to the workforce client. It returns the person's own conversations with the worker on its current flow. The default conversation is first, with isDefault: true. The other conversations follow, with the most recent activity first. It does not show the session of a task, a delegate session, a workstream-lead session, or the project coordinator's session for one project. It never creates a session. findWorkerSession and ensureWorkerSession do not change.

flowchart LR
  subgraph after ["After"]
    A2["workforce client"] -->|"findWorkerSession · unchanged"| D2["default conversation only"]
    A2 -->|"listWorkerSessions"| L2["default first and marked · then every other conversation"]
  end
Loading

What's asked of you. Nothing new. The spec (#3796) settled the direction, and the implementation made no product decision.

Parts worth reviewing closely (for the code reviewer):

  1. How the project coordinator's sessions are removed. The spec says "picked out by its worker". The client does not know which worker is the project coordinator. Thus the list removes each row that has projectId. The create check (installation.ts) refuses projectId on all sessions except the project coordinator's sessions, so the result is the same. FIX-2161 (spec(FIX-2161): an ordinary session of any worker can open on a project #3805) puts an ordinary session's project in workProjectId, which is not a criteria key, so those sessions stay in the list; test/work-project.test.ts checks this now that FIX-2161 is on main (feat(FIX-2161): a user's own conversation with a worker opens on a project #3821). If a later change lets an ordinary session have projectId, this filter must change.
  2. One unpaged listing. The client reads the session listing one time, with no limit. The store then returns all rows, which is how findWorkerSession reads today. It does not page with offset, because the rows can move between pages while their sessions change.
  3. My weak spot: the message-in-default check has no control. It guards behavior that this PR does not change.

Fixes FIX-2158 · Spec: specs/issues/FIX-2158/ (review PR #3796) · Epic FIX-2152 · Goal check: pnpm --filter @flow-state-dev/workforce exec vitest run test/list-worker-sessions.test.ts test/project-coordinator.test.ts -t "no-create|three-sessions|own-only|no-task-runs|message-in-default|no-project-session" → PASS; each of the four controls FAILS (below). The spec's no-other-kinds signal is the test named no-project-session (the retired-terms guard refuses "kinds" there).

How to review this

How to review this. This implements an approved spec — the approach and the numbered
decisions in its DECISIONS.md are already signed off by a human, so please review the
code against that direction, not the direction itself. The canonical set is retained
at specs/issues/<ISSUE-ID>/ on main; Linear links to it and the original merged spec
PR, which keeps review history. Follow-up amendment PRs explain later direction changes.
Current architecture docs remain the authority for shipped behavior (BP-037).

Most valuable here: correctness on the second path (the legacy shape, the null
boundary, the concurrent case, the cancel path), anything deriving an auth or routing
decision from caller-controllable input, and a behaviour the tests assert around
rather than on.

Already settled upstream: the approach and every decision in the spec's DECISIONS.md
(human-approved — if one is wrong, say so as a spec finding and it gets folded back; don't
re-argue it inline), and the conventions in docs/contributing/best-practices.md.

Engineering calls
  • Entry type WorkerSessionEntry = { session, isDefault }, exported from ./browser. The spec left the names to the implementer. Cost if wrong: a rename before the lab wires to it.
  • The criteria-key rule is now one helper (carriesOnly) that findWorkerSession and the list both use, as Cursor asked in the spec review, so the two rules cannot drift.
  • The goal check is two files: test/list-worker-sessions.test.ts (board host: tasks and worker messages) and one case in test/project-coordinator.test.ts (the only host that names a project coordinator).
  • The concept doc did not change. Base terms and Messages on main already say "default conversation" (the spec PR carried that paragraph).
  • A patch changeset for @flow-state-dev/workforce, since a consumer of the published client gets a new read.
Verification

Red (before the code): all 7 new cases fail with TypeError: alice.listWorkerSessions is not a function.

Controls, each run on a temporary patch of listWorkerSessions:

Control Fails
returns findWorkerSession's answer three-sessions (expected [[…]] to deeply equal [[…],[…],[…]]), also no-create, own-only
calls ensureWorkerSession first no-create (expected [[…],[…]] to deeply equal [[…]]), also own-only, no-project-session
include: "dispatch-runs" and no criteria filter no-task-runs (expected [ …(2) ] to deeply equal [ Array(1) ]), also no-project-session
coordinator exclusion removed (projectId allowed) no-project-session only (expected [ { session … } ] to deeply equal [])

workProjectId control: a patch that keeps only the default conversation fails listWorkerSessions lists a session with workProjectId (expected length 2 but got 1).

Green (after merging main): the full workforce suite, Test Files 132 passed (132) · Tests 1598 passed (1598). pnpm turbo run typecheck --filter=@flow-state-dev/workforce: 13 tasks successful. The docs build passes. All 11 process-guard scripts pass locally.

Files
  • packages/workforce/src/workers/client.ts: listWorkerSessions, WorkerSessionEntry, the shared carriesOnly rule.
  • packages/workforce/src/browser.ts: exports WorkerSessionEntry.
  • packages/workforce/test/list-worker-sessions.test.ts: the goal check (new).
  • packages/workforce/test/project-coordinator.test.ts: no-project-session.
  • packages/workforce/test/work-project.test.ts: listWorkerSessions lists a session with workProjectId (added after merging main).
  • packages/workforce/README.md, apps/docs/docs/workforce/workers-on-disk.md: docs.
  • .changeset/list-worker-sessions.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CA2gAQ6waR1yoB9tHNd9fZ

…158)

listWorkerSessions(worker) on the workforce client returns the caller's
top-level sessions of the worker on its current flow, the default
conversation first and marked, the rest by latest activity. Task-run,
delegate, workstream-lead and project-coordinator per-project sessions
are left out. Never creates the default. The criteria-key rule is shared
with findWorkerSession.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CA2gAQ6waR1yoB9tHNd9fZ
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CA2gAQ6waR1yoB9tHNd9fZ
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CA2gAQ6waR1yoB9tHNd9fZ
@vercel

vercel Bot commented Oct 23, 2026 •

Copy link
Copy Markdown

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

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 24, 2026 2:13am UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 24, 2026 2:13am UTC
flow-state-dev-ui Ignored Ignored Preview Oct 24, 2026 2:13am UTC

Request Review

@linear-code

linear-code Bot commented Oct 23, 2026

Copy link
Copy Markdown

FIX-2158

@jhoffner jhoffner self-assigned this Oct 23, 2026
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 23, 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-10-24T02:14:57.739533Z cef9ddc 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.

Copy link
Copy Markdown
Collaborator Author

@codex review

Please look hardest at: (1) the list drops rows carrying projectId to leave out the project coordinator's per-project sessions, relying on the create check in installation.ts refusing projectId on any other worker's session; (2) carriesOnly is now shared with findWorkerSession, so check its non-derivable branch still returns the same rows; (3) the unpaged listing (no limit) in listWorkerSessions.


Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass

Overall the approach is right and lean: one read, no new endpoint, one shared carriesOnly rule. Nothing blocks. Findings below are for the implementing agent to weigh.

1. Drop the message-in-default test (restraint, recommend)

list-worker-sessions.test.ts message-in-default guards send-message routing, which this PR does not touch. The PR body already admits it has no control. It costs the tellsOtto script, a third worker (helper-a), a stores.request.list scan, and sleep-based ordering. Under BP-003 a check that cannot fail when this change is wrong is not evidence for this change. If the routing guarantee deserves a test, it belongs next to send-message. The last assertion (default still first and marked) is already covered by three-sessions. Suggest deleting the case and tellsOtto/helper-a, and fixing the file header that mentions it.

2. Unpaged listing: the claim is unverified (correctness, BP-003)

The PR says the store "returns all rows" with no limit. I checked packages/client/src/session-client/sessions.ts and it just forwards limit. I did not find the server-side default for the top-level session listing (the child-session-routes.ts default is for child runs). If any default cap exists, a user with many conversations silently loses the oldest ones, and the default could be among them, so isDefault never appears. Please confirm the server default with a test that seeds more rows than that default, or pass an explicit large limit and say why. A cheap safety net: if the derived default id is not in rows, that is detectable but not recoverable here, so the test is the real guard.

3. projectId exclusion is a coupling on another package's invariant (design)

carriesOnly(row, WORKER_ONLY) drops any row with projectId because installation.ts refuses it on ordinary sessions. That is correct today and the PR names the dependency, but the only thing tying the two together is a PR description. Add a one-line comment at the listWorkerSessions call site pointing at the create check, so whoever changes that check sees it. No code change otherwise; I would not add worker-kind awareness to the client for this.

4. Small duplication (optional, architecture)

atDerived and listWorkerSessions both do deriveWorkerSessionId plus the same listSessions({ flowKind, userId, state: criteriaState(criteria) }). A tiny shared helper (workerSessionRows(criteria, flow, orgId) returning { defaultId, rows }) would let atDerived become rows.find(r => r.id === defaultId) and keep the "what counts as this worker's rows" query in one place, in the same spirit as carriesOnly. Optional: it is a three-line move, and this PR is already touching both paths. Skip it if it grows the diff beyond that.

5. Docs (minor)

workers-on-disk.md removed the mine = await sessions.listSessions(...) example and now points at listWorkerSessions. Good. The new paragraph is long; the list of excluded kinds (task, delegate, workstream lead, project coordinator, old flow) is the useful part and could be a short bullet list. Style only.

Not worth changing

  • WorkerSessionEntry = { session, isDefault }: fine; a rename before first consumer is cheap.
  • Sort via Number(b.id === defaultId) - Number(a.id === defaultId) || byRecent is compact and tested by three-sessions.
  • Changeset is justified (published client gains a read).

Generated by Claude Code

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: 3189fdbed7

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

…ms guard)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CA2gAQ6waR1yoB9tHNd9fZ

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

Simplification review

Verdict: The direction is right and the PR stays appropriately small (~70 lines of production code in client.ts, focused tests, docs). I would not chase a different architecture here.

Did the approach go too far?

No — the opposite. The epic already rejected the simpler-looking alternative (lab calls SessionClient.listSessions and hand-filters task/delegate/project rows). That spreads exclusion rules into every app and duplicates what findWorkerSession already encodes. One read on createWorkforceClient is the smaller product surface even if the implementation is a bit more logic in one file.

What would have been “too much” (and this PR avoids): a new criteria key, workforce openSession, engine listing API changes, or bundling the FIX-2153 lab. This change set is scoped to FIX-2158.

Cleaner alternatives considered

Alternative Trade-off
Lab-side filter Fewer lines in workforce, more glue and drift in every consumer (rejected in spec / ER-4).
Engine query (“workerId only, no other criteria keys”) Less data over the wire and no client-side filter; bigger cross-package change. Reasonable follow-up if conversation counts or refresh polling hurt — not required to ship this.
Flat list + separate findWorkerSession Simpler return type, worse UX for FIX-2153; rejected in D1.
3rd-party session-list package No established fit; session semantics are FSD-specific.

What’s already done well

  • carriesOnly extraction shares the criteria-key rule between find and listWorkerSessions.
  • Promise.all for derived default id + listing is proportionate.
  • Tests hit real HTTP + engine, assert client output and message routing (not store keys) — matches the spec’s anti-game bar.
  • project-coordinator.test.ts extension for no-other-kinds reuses the existing harness instead of duplicating setup.

Nits / follow-ups (non-blocking)

  1. Shared “conversation row?” helper — Spec review already asked to fold find’s top-level filingSessionId guard into the same helper as carriesOnly so list/find cannot drift when criteria evolve. For WORKER_ONLY today, carriesOnly may already exclude those rows; the win is maintainability, not a known bug.
  2. Unbounded listSessions — Same pattern as existing find / atDerived; fine while conversation counts are small. DECISIONS says the client “pages through”; implementation relies on omitted limit (= unbounded in current stores). Either add an explicit client-side page loop before FIX-2153 polls this, or one sentence in the method doc that callers should expect full scans today.
  3. .sort mutates — Prefer .toSorted(...) (or copy first) so a cached list from the session client is never mutated in place.
  4. Default-first sort — Number(b.id === defaultId) - Number(a.id === defaultId) works but a “partition default, sort rest by byRecent” shape is easier to read.
  5. Consumers (FIX-2153) — Avoid calling findWorkerSession and listWorkerSessions on every refresh; use isDefault on the list entry (noted in DECISIONS).
  6. Tests — sleep(5) for updatedAt ordering is cheap but brittle; harness sequencing or an explicit clock would be sturdier if flakes appear.

Performance

No new hot-path concerns beyond the intentional full listing. Paging at the engine remains the lever if labs poll aggressively.


Approving: the workforce-client layer is the right place, the diff is surgical, and the remaining items are polish or scale follow-ups rather than a rethink.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

@jhoffner

jhoffner commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator Author

Engineering review: FIX-2158 listWorkerSessions. The code is good. The one CI issue below is already fixed by 2e5cc63.

I checked the diff against specs/issues/FIX-2158/ (spec merged in #3796):

  • It reads only and never creates a session.
  • Sessions are filtered by worker on the worker's current flow, and only top-level sessions are listed.
  • taskId, filingSessionId, workstreamId and projectId rows are dropped. The default comes first and is marked, and the rest are sorted by latest activity.
  • carriesOnly is now shared with findWorkerSession, as Cursor asked.

Locally, the goal check passes (list-worker-sessions + project-coordinator, 46/46), and so does the full workforce suite (130 files / 1574 tests). The tests check the client's answer, not stored keys, and the three-sessions activity order is built so that a creation-order list or a plain activity-order list would fail.

  1. Blocking: Process guards fails Fixed in 2e5cc63. check-retired-terms now passes locally. It was failing at the "No retired Workforce term" step (node scripts/check-retired-terms.mjs --list). It flags 7 lines:

    • "person" in packages/workforce/test/list-worker-sessions.test.ts:2, 3, 6, 63, 103, 160. The guard asks for "user".
    • "kind" in the test title at packages/workforce/test/project-coordinator.test.ts:309.

    Rewording these lines should be enough. If you rename the no-other-kinds title, keep the goal-check -t filter in step with it.

  2. Spec fold-back, not a code change: DECISIONS "Decided, not asked" says "Every page is read. The client pages through the listing." The code reads once with no limit (client.ts:212). I checked that the route and the memory, filesystem, pg and sqlite stores apply no default limit, so it does return every row, and Cursor's round-1 note allowed this option. The spec line should be updated to match the code.

  3. For Architect (no change asked): the coordinator's sessions are dropped by projectId on any row, not "picked out by its worker". D1 also says "an ordinary session that carries projectId is listed." Today the result is the same, because the create check (installation.ts projectLinkCheck) refuses projectId on any worker except the coordinator, and FIX-2161 uses workProjectId. Still, the code now differs from the letter of D1, and the PR body already notes the trigger to revisit it.

  4. Minor test gap, optional: no list test creates a top-level workstreamId (workstream-lead) session. The spec's signals don't require one, and carriesOnly covers it.

Once CI on 2e5cc63 finishes green, this is ready for Jake to merge.

— FSD Head of Engineering

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CA2gAQ6waR1yoB9tHNd9fZ

Copy link
Copy Markdown
Collaborator Author

Responses to the engineering review:

  1. Process guards: 2e5cc63 fixed this, and the -t filter in the PR body now names no-project-session.
  2. Spec fold-back: done in 562e979. The DECISIONS line now says "Every row is read": the client reads the listing once, with no limit, and does not page by offset. The line is marked as amended at implementation. The amendment rides on this PR, which is a new PR from main, so the merged spec(FIX-2158): the workforce client lists a person's sessions of one worker #3796 does not change.
  3. I take this as noted, with no change in this PR.
  4. I am not adding a workstream-lead case. carriesOnly covers it, and the spec's signals do not ask for it.

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.

Code Snob. A smaller shape exists. Do not merge the POC.

listWorkerSessions states the exclusions twice, and isDefault repeats what findWorkerSession({ worker }) returns. The test header restates the cases. Three comments restate the next assertion.

Fold #3816 (131371a9a on poc/shorter-worker-session-list) onto 3189fdbed. Do not reset onto the POC. Close #3816 unmerged after this PR lands.

Net −20 (+10/−30). Comments only. The method doc still names the four sessions left out, the default-first order, and that listing never creates. The test header still says what the tests read and that the coordinator case is in project-coordinator.test.ts.

Passed: list-worker-sessions 6 and no-other-kinds. eslint exit 0.

Red: reversing the default-first term listed the default last (three-sessions).

Left as recorded: carriesOnly, the unpaged list, the projectId exclusion, WorkerSessionEntry, both test files, message-in-default, the docs, the changeset.

Tried and left: inlining byRecent. The sort wraps onto three lines and does not get shorter.

View PR

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

Folded from Cursor's #3816 (131371a).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CA2gAQ6waR1yoB9tHNd9fZ

Copy link
Copy Markdown
Collaborator Author

I folded #3816 (131371a9a) into this PR as 3d72a3b. The change is to comments only. The test header conflicted with the "person" → "user" rewording, and I took the shorter POC header. list-worker-sessions and project-coordinator pass (46 tests), eslint passes, and check-retired-terms passes. Close #3816 unmerged after this PR merges.


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.

Code Snob. The note above is the subtraction. Its fold line is stale.

The head moved to 562e9798e while that note was written (2e5cc63d2 says user, not person; 562e9798e is the spec note). Fold 69b336c6c onto 562e9798e. Do not cherry-pick 131371a9a. Do not reset onto the POC. Close #3816 unmerged after this PR lands.

Same −20 (+10/−30) against 562e9798e. The user wording stays. no-project-session passed on 69b336c6c (that case was renamed from no-other-kinds). The POC body still names 131371a9a; it could not be edited.

View PR

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

Copy link
Copy Markdown
Collaborator Author

There is nothing more to fold. 3d72a3b already matches 69b336c6c under packages/workforce/src and packages/workforce/test (git diff 69b336c6c 3d72a3b shows no change in those paths). The "user" wording and no-project-session stay.


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.

Code Snob. Ignore the fold line in the note above. This head (3d72a3b) already is that patch: same −20 against 562e9798e as 69b336c6c. Do not apply it again. Close #3816 unmerged. Do not merge the POC.

View PR

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Merge conflicts

…tId)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CA2gAQ6waR1yoB9tHNd9fZ

Copy link
Copy Markdown
Collaborator Author

The conflict is resolved: main is merged in cef9ddc. The only conflict was the import line in packages/workforce/src/workers/client.ts, which now carries both SET_WORK_PROJECT_ACTION (from FIX-2161) and WORKER_ID_STATE_KEY. The merge also adds the test listWorkerSessions lists a session with workProjectId to test/work-project.test.ts. Locally, typecheck and all process guards pass, and the workforce suite passes (1598 tests). CI is running on the new head.


Generated by Claude Code

@jhoffner
jhoffner merged commit be3016d into main Oct 24, 2026
19 checks passed
@jhoffner
jhoffner deleted the claude/project-thread-bvewrx branch October 24, 2026 11:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants