Repository navigation
spec(FIX-2158): the workforce client lists a person's sessions of one worker - #3796
Conversation
… worker Spec set under specs/issues/FIX-2158/ (SPEC.md, DECISIONS.md, D1 trade-off figure), and the coordination concept's base terms: the derived conversation is the default and the message inbox, not the only one. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xq9XN7ZRxHQXeXbsurX9kC
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
|
@codex review |
|
@codex review This is a direction spec, not code. Please look hardest at:
Generated by Claude Code |
|
Coherence check (FSD Architect): direction is coherent with the FIX-2152 epic's D3 (several sessions per worker, no new criteria key) and keeps session-to-session messages in FIX-2160. Approving the direction; one alignment ask before merge. Same concept paragraph is rewritten in two open PRs. #3789 (FIX-2160) also rewrites the base-terms "A session is where a worker works…" paragraph in Please change one thing here: "the one a message lands in" is only true for a message addressed to the worker. Once #3789 lands, — FSD Architect |
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. |
|
Codex Review: Something went wrong. Try again later by commenting “@codex review”. ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
Second look and architecture pass (FIX-2158)I checked the spec's claims against Above the bar1. The concept-doc amendment contradicts D1 for project coordinators.
2. "Every page is read" has no helper to build on.
Notes for the implementer (not blocking)
Alternatives considered
Direction approved from my side once item 1's wording is settled and item 2's helper location is named. Everything else is the implementer's. Generated by Claude Code |
The default conversation is the inbox for messages addressed to the worker; carrying FIX-2160's wording keeps the two concept edits one rule. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xq9XN7ZRxHQXeXbsurX9kC
|
FSD Architect's alignment ask is folded in 6183b3d. The base-terms paragraph now uses #3789's wording word for word ("one default conversation per user, its message inbox, … the user may open more"), so whichever PR merges second has nothing to reconcile. The "Where it lands" edit is unchanged. It is recorded in @codex review (the last run ended with "Unknown error". Focus areas are the same as above.) Generated by Claude Code |
There was a problem hiding this comment.
Simplify pass — direction looks right
This is a spec-only PR; the simplification lens is mostly “did we pick the smallest design surface?” rather than code churn. On that bar, yes: a workforce-owned listWorkerSessions that reuses listSessions + the same criteria-key rule as findWorkerSession is cleaner than the realistic alternatives (lab-side filtering, a new criteria key per extra chat, or folding “list all” into find as a flag). That matches FIX-2152 D3/ER-4 and keeps engine scope at zero for this issue.
Approach vs simpler paths
| Alternative | Verdict |
|---|---|
Lab calls listSessions({ state: { workerId } }) and filters |
Works mechanically; correctly rejected — duplicates the conversation vs task-run rule in every app (shift-manager already hints at this smell). |
| Engine query: “workerId present, no other criteria keys” | Simpler at runtime (less over-fetch, stable paging story) but bigger change than this issue’s “one client read.” I would not re-gate the spec on it; optional follow-up if conversation counts or poll frequency hurt. |
findWorkerSession + mode: 'all' |
Worse API: find today is deliberately “at most one” on derivable criteria; mixing list semantics invites misuse. Sibling read is the right split. |
| Third-party package | Nothing applies; this is domain semantics on your session model. |
What went further than necessary (spec prose, not product)
Parallel read-only review surfaced duplication, not a wrong fork:
- D1 (threads-twice, criteria-key rule, default-first+mark, excluded session kinds) is narrated in SPEC sign-off, two pipeline mermaid blocks, DECISIONS tree + table + SVG, and the concept amendment. Behavior-preserving trim: one canonical D1 block in
DECISIONS.md, shorter pointers elsewhere; SPEC is over the template word budget mostly for repeats. - Concept Base terms (“lists them all, the default first”) reads broader than D1 — project-coordinator sessions with criteria keys are not in
listWorkerSessions. Tighten to “lists the chats they opened with that worker” (coordinator-per-project stays where you already define it). - Four-people row 3 is a no-op (Today = After); fold caller scoping into “Not done if” or drop the row.
- DECISIONS tree reject X2 (“default left to find”) doesn’t match the “flat list without default mark” row in Considered and dropped — align labels so reviewers don’t see two different rejected options.
None of that blocks direction approval; it’s editorial debt before implementation merge if you care about spec skim cost.
Implementation PR — keep the code simple (carry forward)
When this ships, the highest-leverage simplification is one shared post-list filter in workforce/src/workers/client.ts used by both find and listWorkerSessions (criteria keys + top-level filing guard). That’s where drift would recreate the “lab filters by hand” failure mode.
Pagination: “Every page is read” is fine for lab scale, but note a footgun if the implementer pages with default orderBy: updatedAt while sessions are mutating — rows can move between pages. Either document single unbounded list when limit is omitted (today’s store behavior), page on createdAt then re-sort, or a follow-up keyset helper (pattern: readEveryCollectionPage, not necessarily shared yet). Also worth one line: UI that calls both findWorkerSession and listWorkerSessions on every refresh doubles listing work — lab should prefer list + default mark.
Tests / controls
The anti-game controls (three-sessions, no-task-runs, message-in-default) are strong and keep the implementation from collapsing back into find’s answer. Good spec hygiene.
Summary: Product call and package boundary look correct; I’d approve as-is. Optional pre-impl polish: dedupe D1 prose, narrow concept “lists them all,” and add a short implementer note on pagination + shared filter — not required to sign direction.
Sent by Cursor Automation: Review For Best Approach
…ew notes Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xq9XN7ZRxHQXeXbsurX9kC
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6183b3d134
ℹ️ 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".
…es qualified as worker-addressed Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xq9XN7ZRxHQXeXbsurX9kC
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7140211d84
ℹ️ 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 first ensure Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xq9XN7ZRxHQXeXbsurX9kC
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xq9XN7ZRxHQXeXbsurX9kC
|
One sentence to change before merge, for coherence with FIX-2161 (#3805) and epic ER-8. ER-8 says every lab session works in a project, and FIX-2161 lets an ordinary session carry Please change:
The test that an ordinary project session is listed belongs in FIX-2161's PR, which can create one. No change in direction. — FSD Architect |
…ab session is listed Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xq9XN7ZRxHQXeXbsurX9kC
|
I checked this against
The test that a listed project session appears is left to FIX-2161's PR. The direction is the same: on main today, both rules list the same sessions. Generated by Claude Code |
|
Coherence-clear at 784c98d. D1 now lists ordinary sessions that carry — FSD Architect |
…n D1's Because Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xq9XN7ZRxHQXeXbsurX9kC
|
I took the nit in 5c160b5. D1's Because now says the coordinator's per-project conversations are picked out by their worker, so it matches Locks in. Generated by Claude Code |


Requested by Jake · project thread
listWorkerSessions(worker)and gets each session, the default conversation first and markedGoal: a person who opens more sessions with one worker gets all of them, and only their own, from the workforce client. Messages from other workers continue to go to the one default conversation.
The check reads what the client returns and where the message's request ran. Check: a
packages/workforcetest on the real engine and HTTP router. Controls: the list returns the answer offindWorkerSession(must failthree-sessions), and the list includes dispatch runs with no filter (must failno-task-runs).What changes: one new read on the workforce client.
findWorkerSessionandensureWorkerSessiondo not change, so the code that uses them does not change. The concept doc changes in this PR: the derived conversation is the default conversation and the message inbox, but it is not the only conversation.How: the client gets the worker's flow from the roster and lists the caller's top-level sessions on that flow that name the worker. It removes task-run, delegate and workstream-lead sessions (
taskId,filingSessionId,workstreamId) and the project coordinator's per-project conversations, then puts the derived session first. An ordinary session that carriesprojectId(FIX-2161) is listed.Sign off
The goal, at that size. If wrong: the lab lists sessions with its own code, or a thread shows as a second chat.
The debt: up by one read on the client. It adds
listWorkerSessions. It removes nothing. If wrong: only the lab uses the list.The list holds the person's conversations with the worker, the default first and marked · D1
Trade-off figure: DECISIONS.md → D1.
It comes down to threads mode: a list with task runs shows each thread two times. If wrong: an app that wants task runs in the same list must read them through its tasks.
Open: none. D1 is the decision to examine. Reasons and the options that lost: DECISIONS.md.
Reviewers · look here
Not here: messages to a session that is not the default (FIX-2160), a new criteria key, session titles.
Spec · Decisions · Linear FIX-2158 · epic FIX-2152 (#3783, D3 and ER-7) · 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:
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?
docs/philosophy.md?DECISIONS.md— that's the sign-off surface.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.
design.
Out of scope — deliberately unsettled here, and owned by the implementing agent:
plan on purpose: the implementer works it out against the real code.
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/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 reviewfor the implementer to weigh against real code. It will notbe 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