Skip to content

spec(FIX-2158): the workforce client lists a person's sessions of one worker - #3796

Merged
jhoffner merged 8 commits into
mainfrom
spec/FIX-2158
Oct 23, 2026
Merged

jhoffner merged 8 commits into
mainfrom
spec/FIX-2158

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Someone who… Today After
builds an app where a person has many sessions with one worker Opens more sessions with the session client. The workforce client cannot list them Calls listWorkerSessions(worker) and gets each session, the default conversation first and marked
opens a second and a third session with a worker Cannot find them again from the workforce client Sees all three, most recent activity first after the default
is another person on the same worker id Never sees the first person's sessions The same. The server limits each list to its caller
waits on a background task or thread The task's session is a dispatch run, found through its task The same. The list does not show task sessions

Goal: 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.

flowchart LR
  A["Alice · ensure, then 2 more creates · real HTTP router"] --> T["one task handed to the worker · a task session"]
  T --> B["Bob · own session with the same worker id"]
  B --> L["Alice lists, Bob lists · and a worker message to Alice"]
  L -->|"Alice 3 sessions · default first · Bob 1 · message in default"| P["PASS"]
  C["control · list returns find's answer"] -.-> L
  L -.->|"under the control"| F["must FAIL · three-sessions"]
Loading

The check reads what the client returns and where the message's request ran. Check: a packages/workforce test on the real engine and HTTP router. Controls: the list returns the answer of findWorkerSession (must fail three-sessions), and the list includes dispatch runs with no filter (must fail no-task-runs).

What changes: one new read on the workforce client. findWorkerSession and ensureWorkerSession do 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 carries projectId (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

  • Decisions → D1. Is it correct to remove task-run, delegate, workstream-lead and project-coordinator sessions from the list?
  • Decisions → decided, not asked. The workforce client gets no "open a session" call. Opening stays the create call of the session client, with the worker named. Is that correct?
  • The concept doc diff. Do the new base-terms lines agree with rule 21?

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:

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

… 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
@jhoffner jhoffner added the spec label Oct 23, 2026 — with Claude
@jhoffner jhoffner self-assigned this Oct 23, 2026
@linear-code

linear-code Bot commented Oct 23, 2026

Copy link
Copy Markdown

FIX-2158

@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 23, 2026 10:51pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 23, 2026 10:51pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 23, 2026 10:51pm UTC

Request Review

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

Copy link
Copy Markdown
Collaborator Author

@codex review

This is a direction spec, not code. Please look hardest at:

  • D1: whether dropping top-level sessions that carry any other criteria key (projectId, a legacy top-level filingSessionId) plus leaving dispatch runs out is the right definition of "a person's conversations with a worker". Check it against packages/workforce/src/workers/client.ts (find) and packages/engine/src/routes/session-routes.ts (the listing's default top-level parentage).
  • The concept doc diff: whether the new base-terms lines stay consistent with rule 21 (a message never addresses a raw session).

Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

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 docs/internal/design/workforce-coordination-concept.md, with different wording ("Each worker has one default conversation per user, its message inbox, plus one per project a coordinator coordinates; the user may open more."). They say the same thing, so this is not a fork, but whichever merges second must take the other's text rather than reword it again.

Please change one thing here: "the one a message lands in" is only true for a message addressed to the worker. Once #3789 lands, { session: id } puts a message in a non-default conversation (rule 21). Say "the one a message addressed to the worker lands in" (or reuse #3789's "its message inbox"), so the two edits read as one rule. Your "Where it lands" edit (adding "default") already fits #3789.

— FSD Architect

@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-23T22:53:18.085742Z 5c160b5 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.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Something went wrong. Try again later by commenting “@codex review”.

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

Copy link
Copy Markdown
Collaborator Author

Second look and architecture pass (FIX-2158)

I checked the spec's claims against workforce/src/workers/client.ts, derive-session-id.ts, engine/src/routes/session-routes.ts and client/src/session-client/sessions.ts. Overall the direction holds. One read that sits next to find is the lean answer, and I found no better shape. Two items are above the bar. The rest are notes for the implementer.

Above the bar

1. The concept-doc amendment contradicts D1 for project coordinators.

  • The amended Base terms say a user has "one default conversation per worker, plus one per project a coordinator coordinates", and that "a user … lists them all, the default first".
  • D1's filter keeps only rows whose criteria keys are a subset of {workerId}. projectId is in CRITERIA_STATE_KEYS, so every per-project coordinator conversation is dropped. D1 names project-coordinator sessions as excluded.
  • Rule 21 and the Base terms therefore say "all conversations", while the list returns only the plain worker's conversations.
  • Fix the wording in one place: either the list is "a user's conversations with the worker that aren't tied to a project, task or workstream", or the concept doc's "lists them all" is narrowed to match.
  • The exclusion is the better call, since a project coordinator is reached through its project. But the spec should say so in the PR's Reviewers · look here question, which currently asks only about "removing" these sessions.

2. "Every page is read" has no helper to build on.

  • SessionClient.listSessions returns a single limit/offset page. The cursor loop in client/src/resource-client/read-every-page.ts is for collections, not sessions.
  • find today does one unpaged call and takes mostRecent, so the "as find does" parallel doesn't cover paging.
  • The decision commits the client to a loop that has no existing guard. It needs a page ceiling and a stop on a short page, as readEveryCollectionPage has.
  • The spec should say this is new code. Better, it should say where the loop lives. A small sessions counterpart beside readEveryCollectionPage in packages/client would let the shift-manager's two listSessions call sites (reads.ts:789, :880) use it later.
  • I would not put it privately in workforce. That would be a second paging loop in the repo.
  • Also state the failure mode. On a hit ceiling, throw as CollectionReadStoppedError does, never return a partial list.

Notes for the implementer (not blocking)

  • The criteria-key filter is now duplicated.
    • find (client.ts:246) and the new list would each run CRITERIA_STATE_KEYS.every(key => named.has(key) || !hasOwn(state, key)), plus the filing-session special case at :244.
    • Extract one predicate, say "is this row a session of exactly these criteria keys", and have both call it. Otherwise the two reads can drift, which is the failure the spec is trying to prevent.
    • The restructure is justified here: this PR is the second caller, and the first copy sits 10 lines away.
  • Default detection.
    • atDerived already computes the derived id, and the list needs it again to mark the default.
    • Reuse deriveWorkerSessionId({ userId, orgId, flow, criteria: { worker } }) and compare ids. Don't re-implement it.
    • Note that orgId comes from the roster session (roster()), so the list pays one roster read, one readRoster, and the session listing per call.
  • Which list is needed.
    • The design lists with include unset, so dispatch runs are excluded server-side. The no-task-runs control, which lists with include: "dispatch-runs" and no filter, is the right one.
    • A cheap addition is a case where a delegate session also carries workerId. It confirms the exclusion comes from the server's top-level rule and not only from the client's key filter, since find needs include: "dispatch-runs" for exactly those sessions.
  • Ordering. "Rest by latest activity" depends on SessionSummary carrying an activity timestamp. mostRecent already uses one; reuse its field so the two sorts agree.
  • Test coverage. The goal check seeds the "created before ensure" case. Also cover the empty case: no default yet and no other sessions returns [] without creating anything. The spec says it never creates the default, but no signal tests that.

Alternatives considered

  • Returning { default, others } instead of a flat list with a mark: it is a smaller surface for callers that only need the default. But find already returns the default, and the flat list is simpler for the lab's list view. I would keep the flat list.
  • An include-style option for task runs on the list (the "what would change my mind" in D1) is correctly left out until an app needs it.

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

Copy link
Copy Markdown
Collaborator Author

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 DECISIONS.md → Notes from review.

@codex review (the last run ended with "Unknown error". Focus areas are the same as above.)


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

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2158/SPEC.md Resolved
Comment thread specs/issues/FIX-2158/SPEC.md Resolved
Comment thread specs/issues/FIX-2158/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2158/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2158/SPEC.md Resolved
@jhoffner

Copy link
Copy Markdown
Collaborator Author

Checked 6183b3d: the base-terms paragraph now matches #3789's text word for word, so the two PRs land as one rule. My round-1 ask is closed, and I see no fork with other in-flight work.

— FSD Architect

…ew notes

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

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

Comment thread specs/issues/FIX-2158/SPEC.md Resolved
Comment thread specs/issues/FIX-2158/SPEC.md Resolved
…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

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

Comment thread specs/issues/FIX-2158/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2158/SPEC.md Resolved
Comment thread specs/issues/FIX-2158/SPEC.md Resolved
…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
@jhoffner

Copy link
Copy Markdown
Collaborator Author

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 projectId. projectId is a criteria key (derive-session-id.ts:115-121). So "drop rows carrying any other criteria key" would remove every FIX-2153 and FIX-2157 lab session from the list this PR exists to provide.

Please change:

  • DECISIONS D1, "Locks in": "that carry no criteria key but workerId" → "that are not task-run, delegate or workstream-lead sessions (taskId, filingSessionId, workstreamId), nor the project coordinator's per-project conversations, picked out by its worker. An ordinary session that carries projectId is listed."
  • SPEC "How it reaches the list": the figure node and the sentence "the criteria-key rule find uses" → "drop task-run, workstream-lead and project-coordinator sessions".
  • The control: "the criteria-key filter removed" → "the coordinator exclusion removed". no-other-kinds stays as it is.

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

Copy link
Copy Markdown
Collaborator Author

I checked this against derive-session-id.ts on main (projectId is in CRITERIA_STATE_KEYS) and against #3805's D1. It is correct, and I folded it in 784c98d as you worded it:

  • In D1's Locks in, the excluded sessions are now named by kind (taskId, filingSessionId, workstreamId, plus the project coordinator's per-project conversations, picked out by its worker). An ordinary session that carries projectId is listed. I updated Because and the "worker id, not criteria" bullet to match.
  • In SPEC How it reaches the list, the figure node and the sentence now drop task-run, workstream-lead and project-coordinator sessions.
  • The control now reads "the coordinator exclusion removed". no-other-kinds is unchanged. I also updated the "How" line in the PR body.

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

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Coherence-clear at 784c98d. D1 now lists ordinary sessions that carry projectId and excludes only task-run (taskId), delegate (filingSessionId), workstream-lead (workstreamId) and the project coordinator's per-project sessions picked out by its worker. That matches #3805's D1 and epic ER-8, so there's no fork. The SPEC figure and the control line agree with it. One small wording nit you can take or leave: the Because row lists "the project coordinator's projectId" among the marking keys, but the coordinator's sessions are picked out by worker, not by that key, as Locks in says. Not blocking. Deferring the listed-project-session test to FIX-2161's PR is fine.

— 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

Copy link
Copy Markdown
Collaborator Author

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

@jhoffner
jhoffner merged commit d279e41 into main Oct 23, 2026
28 of 29 checks passed
@jhoffner
jhoffner deleted the spec/FIX-2158 branch October 23, 2026 23:35
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.

2 participants