Repository navigation
spec(FIX-1788): A worker is a private resource its owner holds, run by the shared flow it names - #2812
Conversation
…y the shared flow it names Retained spec set at specs/issues/FIX-1788/: workers as user-scoped rows, one copy per flow, a server-owned session link set once on the first turn, per-turn configuration and a per-worker private key; old hires carried by one operator step, an org-wide hire copied to each member who used it. Four PRs, engine first. One open ask (Q1: a fork copies or follows the standard worker's shared instructions). Includes poc/flow-inventory/, the executable check behind the flow list (23 flows over 94 WORKER.md files; totality asserted, control fails). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
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. |
Second look + architecture pass (spec FIX-1788)Verdict: The approach is appropriately scoped. The four-PR shape (new model beside the old in P2, upgrade in P3, switch in P4) is right. Two small trims and one architecture suggestion follow. Estimates are forward-looking (est.). Trims (second-look)
Architecture opportunity (improve-codebase-architecture)
Considered and left alone
Generated by Claude Code |
There was a problem hiding this comment.
Direction
The epic’s privacy spine (user-scoped worker rows, one shared flow copy per kind, server-owned session link set once, operator upgrade for legacy hires) is the right size for FIX-1788. The spec does the work of showing why smaller cuts fail: org-scope narrowing alone, caller-seeded links (epic POC O1), and runtime dual-read for old hires are each named and rejected with a concrete price. Sixteen plan surfaces and four stacked PRs look heavy, but they track real seams (engine session ownership, workforce registration, per-worker config/grants/isolation, migration) rather than speculative layering.
I do not see a materially simpler approach that still meets the stated goal and anti-games (two users, two hosts, leg c on a store main wrote, controls that must fail). Deferring singleton registration (S10) or the upgrade step (S13) would strand hires or leave the org-wide hole open.
Where complexity is self-inflicted (worth trimming before implementation)
1. Parallel prose, not parallel concepts. The link contract, first-turn admission, per-turn config load, worker-keyed isolation, and grant narrowing are described in overlapping bullets across DECISIONS.md (“Decided, not asked”), SPEC.md, PLAN.md guardrails/sketch, BUSINESS-RULES.md, and DOCS.md. Behavior is consistent today; the risk is implement-time drift when one file is edited without the others. Suggestion (optional, not blocking direction): treat PLAN.md §Surfaces + §Sketch + pinned names as the procedural canonical layer; shorten “Decided, not asked” to D1/D2/Q1 plus pointers; keep BUSINESS-RULES.md as the behavioral contract only.
2. S6 / S7 / S8 are one mental model in three table rows. Per-turn configuration, private state keyed by worker, and grants per turn are all “what this worker runs with on the shared copy.” Collapsing them in the plan narrative (one section, three sub-bullets) would not change the PR stack but would reduce the chance S7/S8 drift independently (e.g. skills key vs grant narrowing).
3. DOCS.md draft vs PLAN.md pinned names. The durable-hire draft still shows createSeatHireBlocks / roster-admin while the plan explicitly defers seat* renames to FIX-1796 and pins worker, workforce/workers/*, workerId. That is fine for a draft, but P4 reconciliation is easy to under-specify. A short “shipped names” callout in DOCS.md keyed only to the three pinned names would lower implementer guesswork.
4. Flow inventory POC — fit for purpose; small polish only. The script matches the retained-census pattern (FIX-1507, FIX-817, etc.) and is not duplicating fsdev or graft for totality proof. If this ever graduates to CI, consider one git ls-files -z pass (FIX-1748 style), deduping definedIn hits, and a single-pass index instead of O(flows × sources) scans — not needed for spec evidence at ~sub-second runtime.
5. PLAN V0 second half. Re-running the inventory plus manually rg’ing every hireWorkforce call site is two dimensions of “which flows.” Optional: a tiny sibling census (like FIX-1507) for runtime registration sites would mirror the WORKER.md totality story; I would not block the spec on it.
6. Nits. Carol in BUSINESS-RULES.md is unused; BR “Proved by” and PLAN V-ids duplicate the same mapping (pick one owner). Q1 remains the real open product fork — copy vs follow is well framed; resolving it at the gate unlocks V8/user-docs wording.
Third-party / reuse
Using orchestration’s frontmatter parser in the POC would align with hire-time parsing but costs the zero-install story; keeping regex + documenting the limit is reasonable for retained evidence. Production implementation should reuse existing workforce/orchestration paths (readDeclaredFlow, discoverWorkforceCode per root) rather than re-deriving heuristics from the POC.
Verdict
Approve for direction. The approach is ambitious because the problem is; the spec is coherent, POC scope is disciplined (inventory only, no redundant engine POC), and rejected alternatives are explicit. Addressing doc topology and DOCS/pinned-name alignment before or during P1–P2 would simplify the implementer’s job without changing the architecture.
Sent by Cursor Automation: Review For Best Approach
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8fac75c999
ℹ️ 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".
…ks, upgrade collisions Folds: BR-6/22a/33a apply FIX-1789's standard-only flag on save, load and the step; BR-25a stamps writtenBy from the link (FIX-1789 BR-20/D1); BR-13a makes the first-turn link atomic; BR-19a narrows readability of a session whose flow is gone to today's engine behaviour; BR-30/31 copy org-wide memory and rename on id collision instead of skipping (D2). Below-the-bar feedback recorded verbatim in PLAN.md -> Notes from review. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
|
|
||
| ```diff | ||
| - clients.actions("acme.~alice.researcher").sendAction("run", { message }, { sessionId }) | ||
| + clients.actions("agent").sendAction("run", { message, worker: "researcher" }, { sessionId }) |
There was a problem hiding this comment.
I'm not sure exactly what clients.actions("agent") is, but I think its weird that the worker is requested as part of the action message.
Wouldn't the worker be decided by the session? You can't change the worker of the session, they are linked.
There was a problem hiding this comment.
from: fsd-head-of-engineering / session: em-fix-1786 / kind: decision
Agreed: the worker belongs to the session, not to a message. clients.actions("agent") is the app's client for the agent flow. Today each hire is its own flow (acme.~alice.researcher). After this change every worker runs on one shared agent flow, so something has to say which worker a session runs. The spec put that in the first message only because session create runs no flow code. That is an implementation convenience, and it leaks into the API.
Decision for the round-2 fold: the worker is named once, at session create: create("agent", { worker: "researcher" }).
- The server checks it right there. The worker must be the caller's own or a standard worker, and it must name this flow.
- The server stores it where only the server writes. Actions never carry
worker. - A session without a worker is refused at the door.
- Every path that opens a session (a person, a task, a mailbox post) names the worker at create.
- The link never changes.
This is the session-record form the epic's D3 already anticipated ("FIX-1788 needing the link before any flow code runs, at admission: then a server-only field on the session record"). So it is change 3 in its other shape, not a fourth Layer 1 change. The fold should state the mechanism (where create runs the check) and keep the caller-link control failing.
Generated by Claude Code
There was a problem hiding this comment.
from: fsd-head-of-engineering / session: em-fix-1786 / kind: decision
Follow-up from Jake: the app-facing shape should be session-first. Also, clients.actions("agent") is not a real API. The spec made it up. Today the client has createClient({ flowKind }) (flow-level sendAction(action, input, { sessionId })) and createSessionClient().createSession({ flowKind, userId, state }).
Decision for the round-2 fold. The diff in SPEC "What an app writes" and DOCS.md becomes, roughly:
const session = await getWorkerSession({ worker: "researcher" }) // or { worker, sessionId } to resume
await session.sendAction("run", { message })getWorkerSessionderives the flow from the worker's own configuration, so the app never namesagent.- Without a
sessionId: it creates a session, with the link set and checked at create as decided above. - With a
sessionId: it resumes that session, and is refused if the session is linked to a different worker or belongs to another user.
- Without a
- The returned handle is bound to one session.
sendAction(action, input)carries no flow, no worker and nosessionId. - Where it lives: the worker-aware helper is a Workforce export (Layer 2), and the session-bound handle is a small addition to
@flow-state-dev/client, if one isn't already there. Neither is an engine change. Pin the two names the docs teach; the exact signatures are the implementer's. - Docs: use the same shape in DOCS.md and in the goal check's legs.
Generated by Claude Code
There was a problem hiding this comment.
from: fsd-head-of-engineering / session: em-fix-1786 / kind: decision (supersedes my previous reply's helper names)
Jake: if the existing API is coherent and the example just doesn't show enough of it, show more of it rather than inventing new helpers. The existing client is coherent, so drop getWorkerSession and the session-bound handle. The round-2 fold replaces the one-line clients.actions(...) diff (that API doesn't exist) with the whole app-side flow on today's client, and marks only the parts that are new:
import { createClient, createSessionClient } from "@flow-state-dev/client"
const sessions = createSessionClient({ baseUrl })
// 1. The user's workers. Each row names the flow that runs it (worker.flow, e.g. "agent"). Read via FIX-1788's roster read.
const researcher = workers.find((w) => w.id === "researcher")
// 2. Find this worker's sessions, or start one. The link is set and checked at create.
const [existing] = await sessions.listSessions({ flowKind: researcher.flow, userId, worker: "researcher" }) // NEW: `worker` filter
const session = existing ?? await sessions.createSession({ flowKind: researcher.flow, userId, worker: "researcher" }) // NEW: `worker` on create
// 3. Talk to it: an ordinary action on that session. No worker in the message.
const agent = createClient({ flowKind: researcher.flow, userId })
await agent.sendAction("run", { message }, { sessionId: session.id })React apps use the same steps through the existing session hooks. Show that variant in DOCS.md if the hooks need a worker pass-through.
The fold pins only the two additions (worker on createSession, worker on listSessions) plus the roster read that returns flow, and states how each is checked: a session create naming someone else's worker, or a worker whose flow differs, is refused. Nothing else in the client changes.
Generated by Claude Code
There was a problem hiding this comment.
from: fsd-head-of-engineering / session: em-fix-1786 / kind: decision (adds to the superseding reply)
Jake: keep today's client for create and send, but add one self-documenting lookup helper, findWorkerSession. Call sites then read clearly, and they don't all change when the lookup logic does. Sessions will also be looked up by worker plus a task or a workstream.
For the round-2 fold:
- Pin
findWorkerSession({ worker, ... })as a Workforce export. It returns the caller's session linked to that worker, or none. Its matching criteria are an extensible object: FIX-1788 shipsworker, FIX-1794 addstaskId, and FIX-1793 addsworkstreamId, each as a later field on the same helper. Leave room for that; don't guess the later keys' semantics. - It's built on
listSessions({ …, worker }), which stays the primitive. Creating a session is stillcreateSession({ …, worker }). - The example in SPEC and DOCS step 2 becomes:
const session = (await findWorkerSession({ worker: "researcher" })) ?? await sessions.createSession({ flowKind: researcher.flow, userId, worker: "researcher" }) - It is scoped to the caller. It never returns another user's session, the same rule as the list.
Generated by Claude Code
There was a problem hiding this comment.
from: fsd-head-of-engineering / session: em-fix-1786 / kind: decision (adds to the findWorkerSession reply)
Jake: pair the lookup with ensureWorkerSession({ worker, ... }), which returns the matching session and creates it if there isn't one. Both are Workforce exports, they take the same criteria object, and they share one lookup path, so a change to how sessions are matched lands in one place.
findWorkerSession(criteria)returns the caller's matching session, or none.ensureWorkerSession(criteria)returns that session, or creates one throughcreateSession({ flowKind: <worker's flow>, userId, worker }), with the link set and checked at create, and returns it. The app never names the flow.- Racing calls: two concurrent
ensureWorkerSessioncalls with the same criteria must not create two sessions. State how this is guaranteed, or say plainly that the second create returns the first session. - Example: SPEC and DOCS step 2 becomes
const session = await ensureWorkerSession({ worker: "researcher" }). ShowfindWorkerSessionwhere an app only wants to check.
Generated by Claude Code
|
Spec review, round 1. Triaged at de74dde. Every inline thread has its own reply. This comment covers the two top-level reviews. Folded (rules, plan and docs; the approach, D1, D2 and Q1 are unchanged):
Review comment from the owner's account, item by item:
Cursor (approve for direction): items 1, 2, 3, 5 and 6 and the reuse note are recorded verbatim in PLAN.md → Notes from review. Carol is removed inline. Item 4, the POC polish, is dropped: the POC is retained evidence. Generated by Claude Code |
|
from: fsd-head-of-engineering / session: em-fix-1786 / kind: decision Round-2 fold checklist for this spec, gathered in one place:
Generated by Claude Code |
|
I agree with the recommendations |
|
from: fsd-head-of-engineering / session: em-fix-1786 / kind: decision Recording Jake's answer at this gate (2026-10-06, comment 6024639440, "I agree with the recommendations"):
The round-2 fold carries these alongside the checklist above. The merge waits for the round-2 head. Generated by Claude Code |


acme.~alice.researcheragent) and names the worker. The server links the session one timeGoal: in one org, the workers of a user are theirs alone. Each worker runs on one shared copy of its flow, with its own memory. A user hires or forks a worker without a restart, and cannot change a standard worker. Each hire from before the upgrade moves to its owner.
The check reads what each caller gets over HTTP. It does not read the link value. Check:
goals/workers-as-resources/keeps-each-users-workers-their-own/, scripted model, two hosts on one store. Controls that must fail:GOAL_CONTROL=org-scoped-workersandGOAL_CONTROL=caller-link. Why this goal and not a smaller one: SPEC.md.On the left, a worker is a registered copy. On the right, a worker is data, and all workers share the copy.
How: a worker is a row in the user scope of its owner. A standard worker comes from the files. The first turn of a session names a worker. The server checks the worker and writes the link into session state that a caller cannot write. Each turn loads the worker again.
Sign off
The goal, at that size: private workers, one copy per flow, hires without a restart, and each old hire moved to its owner. If wrong: we close the privacy hole and leave the workers of a deployment behind.
Does a fork copy the shared instructions of a standard worker, or follow them? · Q1 · open
In plain terms. Alice forks the researcher to change its model. Next month the installation improves the instructions of the researcher. With copy, her fork keeps the old text until she forks again. With follow, her fork gets the new text and keeps her model change.
The trade-off. Copy is the rule for library copies: nothing changes under the owner. Its cost is forks that go stale. Follow keeps forks current. Its cost is a layered configuration, and a file edit then changes what runs with the access of each user who forked.
My recommendation: copy. One rule for each copy that a user holds. We can add follow later as an option. We cannot easily remove it later.
What would change my mind: users who fork only to change one setting, while the core instructions change each week.
If wrong: forks drift until users fork again, and they lose their edits. Easy to reverse, because follow is an addition.
Hires from before the upgrade move in one operator step · D1
It comes down to the old copies: a read at run time keeps them alive for all time. If wrong: after an upgrade, users wait for an operator.
A worker hired for the whole org goes to each member who used it · D2
It comes down to what each person had: no user loses a worker, and no user gets a new one. If wrong: copies that a team did not expect, or a worker that people used is gone. What would change my mind: no deployment uses an org-wide hire today, other than the chief-of-staff seat. Then the step only reports those hires, and BR-30 and BR-31 get smaller.
Q1 is the one to weigh. Reasons and what lost: DECISIONS.md. The cases: BUSINESS-RULES.md.
Reviewers · look here
main. Is that true for each PR alone?Not here: the worker-flow declaration shape (the epic's Q1, chosen at FIX-1789's gate), the coordinator, the library, and the removal of instances and pins (FIX-1798).
Spec · Decisions · Rules · Plan · Docs · Evolution · Linear FIX-1788 · epic FIX-1786 (review #2795) · builds on the epic's end-state POC · merges after human approval and required checks (contract)
How to review this — altitude, what's in scope, what's deliberately unsettled
This is a direction set, not an implementation. 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.BUSINESS-RULES.mdmisses, or a rule that would invalidate the design.DOCS.mdand their fit with the rules; a missing ormisleading lineage claim in conditional
EVOLUTION.md.Out of scope — deliberately unsettled here, and owned by the implementing agent:
PLAN.mdpins on purpose.PLAN.mdleft open on purpose — it is directional by design, and a gap at thataltitude is intended, not an omission.
or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
decisions don't say is.
PLAN.mdmay include a rough pseudocode sketchshowing the shape of the proposed solution. It is knowingly incomplete, is not real code,
and is not what will ship. Review it for directional viability only. Do not report
that it lacks error handling, omits edge cases, names things that don't exist in the repo, or
wouldn't build: all of that is true on purpose.
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
PLAN.md → Notes from reviewfor the implementer to weigh against real code. It will not be argued with, and itwill not be folded into the design prose. Please don't re-raise it: one mention is enough.
The one exception is the sketch and the POC. Line-level feedback on either is dropped, not
recorded — there is nothing for an implementer to weigh about code that isn't shipping. Feedback
about their 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.
Engineering calls — decided, not asked
agentchange takes either shape.POC — which flows the switch converts
It answers which flows the repo's workers name and where each is defined, with a totality assertion and a control that fails. It is retained evidence, not production code. The premise of the design (a shared copy, a server-owned link) is the epic's POC.
🤖 Generated with Claude Code
https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Generated by Claude Code
Generated by Claude Code