Repository navigation
feat(workforce): workers run only on registered worker flows (FIX-1789) - #2847
Conversation
hireWorkforce takes the installation's worker flows as `workerFlows`
(renamed from `kinds`, with SeatHireCapabilityOptions and
reloadHiredSeats) and checks every one, the built-in `agent` included,
against the worker contract before any worker is hired: it takes the
configuration a real hire supplies, by key and by value; it has exactly
one door; and any `writtenBy` it declares is the shared-resource field.
One problem refuses the whole call, once per flow. The check is exported
as `workerFlowProblems` for a library's own tests.
An entry `{ flow, standardOnly: true }` keeps a flow for the workers the
installation's files define. A record carrying an owner pin (a runtime
hire, a stored roster row) is refused on it, after the `agent` default;
a stored row refused this way is reported and left as stored.
`sharedResource` declares an org-scoped collection whose entries carry a
required `writtenBy: { userId, workerId? }`, and `writeShared` stamps it
from the session, never from input.
The built-in agent keeps its skills drawer at user scope, off org scope.
The two-door warning is gone: none or two doors now refuse.
Every worker-flow map in the repo was run through the check (V0). Test
and goal fixtures without a door got one; DevForce's EM gets a real door
that files a feature from `<issue-slug>: <what>`. New goal:
goals/worker-contract/runs-workers-only-on-registered-flows.
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
|
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: a948c856-ec33-4600-b502-1de5ce26b1b0) |
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. |
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: f58d5e06-9fca-4b43-af4b-65269f6dd8d4) |
There was a problem hiding this comment.
Problem
Workers could run on flows the installation never registered (or on the built-in agent when the app meant to reserve it for file-defined seats). FIX-1789 needs a single, loud gate before mint: only registered worker flows, plus standardOnly for user-owned workers.
Verdict
Approve. The split — resolveWorkerFlows + registration-time workerFlowProblems + sharedResource/writeShared — matches the locked contract (structural admission at hire, door via seatDoorOf, attribution on declared writtenBy). I don’t see a materially simpler design that still covers hand-built hireWorkforce({ workerFlows }) and library flows tested without codegen.
A wrapper-only path (defineWorkerFlow / Shape B) would shrink call sites but was correctly rejected: it wouldn’t catch flows registered as plain defineFlow results. Renaming kinds → workerFlows without the contract would be smaller diff but wouldn’t deliver the epic.
Where complexity crept in (non-blocking)
- Check 1 couples to error-string shape —
configurationProblemmint-probes thencontractKeysRefusedparsesdescribeFlowConfigIssueswording. If core rephrases or the throw isn’t a config refusal, you can get a silent pass on configuration. Higher-confidence simplification (when you’re willing to touch it): read the flow’s closedconfigSchemaandsafeParse(CONTRACT_PROBE_BAG)(or export/reusedescribeFlowConfigIssuesfrom core) instead of parsing messages; keep the mint probe only if blockflowConfigSchemamust be part of “hire bag admissible.” - Doc drift —
worker-flow-contract.tssayscontractKeysRefusedis what hire uses for mint refusals;hire.tsonly doesrefuse(messageOf(error)). Either wire a shared reader for worker-facing mint errors (oldadmissionHintintent) or trim the comment. - Duplicated attribution rules —
WRITTEN_BY_ACCEPTS/WRITTEN_BY_REFUSESparallelwrittenBySchemainshared-resource.ts. One helper next towrittenBySchemawould keep check 3 and the helper in sync. - Naming debt — public API is
workerFlows, but user-visible strings still say “kind” (missingKindReason,KindRefusedHireError) and codegen still exportskinds. Fine for this PR; FIX-1796-style sweep would reduce cognitive load. - POC mirror —
specs/issues/FIX-1789/poc/.../contract.tslargely copies production; pointing the POC at@flow-state-dev/workforceexports would avoid two implementations (process hygiene, not runtime).
What’s working
CONTRACT_KEYSderived fromworkerConfigSchema().shape+ probe-bag sync test.WeakMapcache on flow identity — right tradeoff for reload.standardOnlyas a smallWorkerFlowEntryshape.- Goal
runs-workers-only-on-registered-flowsexercises the real hire path. - Built-in skills
scope: "user"aligns with the architecture doc.
Skipped (larger than this PR)
- Reload doing N×
hireWorkforce([one row])— pre-existing; contract adds only once-per-flow cost. - Replacing the whole contract with a third-party package — nothing fits this FSD-specific door + hire-bag model.
No changeset concern from me; workforce surface change is appropriately covered.
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: ae72c9d583
ℹ️ 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".
There was a problem hiding this comment.
Code Snob
The contract is the size it has to be (worker-flow-contract.ts, shared-resource.ts, the hire check). What can go is the door pasted into the fixtures.
Eighteen goal flows repeat the same message door that answers Heard: …, and the two shift-manager labs each carry a copy of hearing-door.mts. One helper covers the identical copies: #2849
That draft does not merge. Fold goals/lib/worker-door.mts and the single packages/shift-manager/test/fixtures/hearing-door.mts into this branch, then close the POC unmerged after this lands.
Left alone on purpose: the host door that returns {}, and the worker-contract goal's doors, whose replies name the flow. Also drop the sentence in worker-flow-contract.ts that says hire words mint refusals with contractKeysRefused. Hire no longer calls it.
Sent by Cursor Automation: Code Snob
- Check 1 fails closed: a mint refusal in no shape the reader knows is a problem, not a pass. Parser tests cover each shape on their own. - Check 3 finds writtenBy through refine, transform, pipe, intersection and union, and compares parsed output, so a field that drops workerId fails. The rule lives beside writtenBySchema (isSharedWrittenBy). - workerFlowProblems reports a name mismatch along with every other problem. - Refusals and the missing-WORKER.md diagnostic say worker flows and workerFlows; README signatures and the architecture quick reference updated (skills drawer at user scope). - Docs: declared vs hired workers defined once; standardOnly behaviour on hire and reload stated; writtenBy guarantee stated plainly. - Fixture doors: one goals/lib worker door and one shift-manager hearing-door, replacing the per-goal copies. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: 9b2305dd-d836-417a-b821-cad8afd32f87) |
|
@codex review a5672b3 rewrites the attribution check ( Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a5672b3195
ℹ️ 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".
…ues (FIX-1789)
- Check 3: a resource that declares writtenBy must be built by
sharedResource(), which marks its output with a non-enumerable brand
bound to the schema it built. A hand-rolled resource is refused even
with the right shape; a spread or schema-swapped copy loses the brand.
Value probing and output comparison are gone.
- Check 1: core's config refusals now throw FlowConfigRefusalError with
structured issues ({ path, code, message }), message unchanged. The
contract reads those, not the text: a whole-bag issue is always a
problem, and a `; ` inside a custom message is one issue.
- core: config-refusal errors carry structured issues; additive. Patch
changeset.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: af6f6ff1-81be-4eed-af97-fa9f11fb6adf) |
|
@codex review 49d6397 replaces both checks at the root. Attribution is judged by which helper built the resource ( Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 49d6397c22
ℹ️ 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".
| const writtenBy: WrittenBy = | ||
| typeof seatId === "string" && seatId.length > 0 ? { userId, workerId: seatId } : { userId }; |
There was a problem hiding this comment.
Derive worker attribution from worker provenance
When an ordinary, non-worker flow has an unrelated nonempty configuration setting named seatId, this branch treats that key as proof that a worker is running and stamps the human write with a false workerId. Core does not reserve seatId, and SharedWriteContext accepts arbitrary flow configuration, so writeShared needs a workforce-specific provenance signal rather than the presence of this generic key.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Declined in this PR. You're right that seatId is not a reserved key in core. But FIX-1788's approved plan replaces this exact source with the server-only session link: "If its singleton cutover hasn't landed, the helper reads seatId, and FIX-1788 switches it". A different provenance signal added here would be code FIX-1788 then deletes. Today writeShared's documented use is in worker flows, where seatId is stamped by the hire. I'm leaving this thread unresolved so the owner can decide, since it's about whether attribution is correct.
Generated by Claude Code
…FIX-1789) - Check 1 compares the probe mint's contract keys with the bag it was given; a transform over `seatId` (or any contract key) is a problem that quotes the key and both values. - A block requirement hidden behind a flow's own required setting is left to the hire, which refuses with core's own error; a test pins it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: 14f06044-96ed-475b-b0d0-be4ca181fd70) |


The problem
Today any flow passed to the hire can run any worker. A worker flow with no door can still be hired, but it can't take a message. A flow that refuses a hire's configuration fails only at the moment someone hires a worker onto it. The built-in
agentkeeps each worker's skills drawer at org scope, and nothing on a shared entry says who wrote it.What this does
The app passes its worker flows to the hire as
workerFlows. Before any worker is hired, each flow, the built-inagentincluded, is checked for three things:writtenBywas built withsharedResource().One error names every problem with every flow. A flow passed as
{ flow, standardOnly: true }refuses hired workers, which are runtime hires and reloaded roster rows.sharedResourceandwriteSharedstamp the writer from the session. Theagentdrawer moves to user scope.What's asked of you
This implements the approved direction. One call is yours:
DevForce's EM now takes a person's line, and files the feature it names
<issue-slug>: <what>and files that feature; any other line files nothing, and the EM says so. Inbox's reply under the EM's ask is now on. FIX-1690 had it off.Parts worth reviewing closely
For the code reviewer:
worker-flow-contract.tschecks the configuration by minting the flow with a full probe bag. It reads the structuredissuesthat core now attaches to a config refusal (FlowConfigRefusalError), not the message text. An issue on the whole bag always refuses the flow, and so does any refusal it can't read.sharedResource()marks its output with a non-enumerable brand, bound to the schema it built. Spreading the resource or swapping its schema loses the brand.ownerPin(hire.ts). No new field was added.Fixes FIX-1789 · spec
specs/issues/FIX-1789/onmain(review #2811, amendments #2841, #2843) · epic FIX-1786 · goalgoals/worker-contract/runs-workers-only-on-registered-flowsPASS, three source-revert controls FAIL their leg only.How to review this
Engineering calls
writtenBymust be built withsharedResource(), which owns the field. This narrows the spec's check 3 from "judged by what it accepts" to "built by the helper". Sampling values can't prove that an arbitrary Zod schema stores{ userId, workerId? }: review found a union with an unsigned branch, a transform of the whole entry, a broader field and.or("system"), and all four passed the probes. The repo has no hand-rolledwrittenByresource except the goal's deliberately broken one. If wrong: a hand-rolled resource with a correct full shape is refused. Switch it tosharedResource.FlowConfigRefusalErrorwithissues: { path, code, message }[]. The message and the error'snameare unchanged.unrecognized_keysgives one issue per key, at that key's own path. Two codes are the framework's own:no_config_schema, andblock_contributes, where an empty path means the whole bag. The contract reads these instead of parsing text. As a result, a block that transforms the whole bag is refused, and a custom message containing;stays one issue. If wrong: none on the message side; a caller that checksinstanceof Errorstill matches.@flow-state-dev/coregets apatchchangeset.flowConfigSchema.admissionHintis removed. After registration it could never fire. If wrong: none.writeSharedcreates or replaces the entry. The entry names whoever wrote last. FIX-1793 decides who may write.raiseAsk, as goal leg AR-6 expects.kinds, andKindRefusedHireErrorkeeps its name. Only the generated export's type is nowHireOptions["workerFlows"]. Both renames are FIX-1796's. The refusal text now says "worker flows".Everything else: verification, V0, files
Goal, as the spec drew it
pnpm tsx goals/worker-contract/runs-workers-only-on-registered-flows/run.mts(model-free), on the current head:The runner can't load on
main, becauseworkerFlows,sharedResourceandwriteShareddon't exist there. So each leg's control reverts that leg's mechanism tomain's behaviour, and each fails only its own leg:[a] … hired 5 worker(s).scope: "user"off → FAIL[b] alice's drawer rows are in the org's cellsand[b] bob's run touched alice's drawer.[c] bob's own worker runs on the kept flow "coordinator".Unit tests, red then green
worker-flow-contract.test.ts:.or("system"), a schema swapped onto a spread or built resource, a block transforming the whole bag, a;inside a custom message, a misnamed doorless flow, and the wrapped loose schemas.flow-config.test.ts(core): 5 tests on structured issues. Each is a real mint refusal, with the message unchanged. Green: 46.worker-flow-registration.test.ts(V2–V4, V7, runtime hire),shared-resource.test.ts(V5, real engine),agent-worker-own-state.test.ts(V6, real engine): red onmain's behaviour, green now.Suites (current head): workforce 90 files / 1415 tests · core 143 / 2302 · shift-manager 33 / 374 (1 skipped) ·
pnpm typecheckpasses, boundary and control-shape guards included. The goals touched by the fixture-door refactor pass, apart from the two that fail the same way onmain:a-mailbox-holds-the-work-a-seat-drains(V14) andmanager-queue-lab/it-stands-the-team…(its diff gate depends on the branch).V0: every worker-flow map in the repo went through registration, on the real hosts, test suites and model-free goals. Each flow that failed was fixed here. Flows with no door now use one shared door:
goals/lib/worker-door.mtsfor goals andpackages/shift-manager/test/fixtures/hearing-door.mtsfor the labs (folded in from #2849). Flows missingseatPackages: pentestprobeand the workforce-seats control pairs. DevForce's EM got a real door (block 3).What the spec missed (DOCS.md): moving the drawer made four doc claims false. They were fixed in
built-in-worker.md(two sentences and the SVG),overview.md, the workforce README anddocs/architecture/workforce-default-worker-kind.md.Changesets:
minorfor@flow-state-dev/workforce(epic D9),patchfor@flow-state-dev/core(structured config-refusal issues).Files:
packages/workforce/src/{worker-flow-contract,shared-resource}.ts.hire.ts,seat-hire-blocks.ts,roster/{check,reload}.ts,agent-worker-flow.ts,codegen/render.ts,loader/read-workforce-directory.ts,index.ts.packages/core/src/helpers/flow-config.tsandflow/defineFlow.ts.kindstoworkerFlows.goals/worker-contract/runs-workers-only-on-registered-flows/.🤖 Generated with Claude Code
https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Note
High Risk
Changes the single admission gate for hiring, user-scoped agent skills (data isolation), and durable roster reload rules for standard-only flows—areas that affect multi-tenant behavior and boot-time failures.
Overview
FIX-1789 tightens workforce hiring: apps register worker flows via
workerFlows(renamed fromkinds), andhireWorkforce/reloadHiredSeatsvalidate every registered flow—including built-inagent—before any seat is minted.A flow must compose
workerConfigSchema(), expose exactly one public “door” action (userMessage+{ message }), and declare any resource withwrittenByonly throughsharedResource()/writeShared(). Failures aggregate in one boot error viaworkerFlowProblems. Entries can be{ flow, standardOnly: true }so runtime hires and reloaded roster rows cannot run on flows reserved forWORKER.mdworkers.@flow-state-dev/corenow throwsFlowConfigRefusalErrorwith structured{ path, code, message }issues when a config bag is refused, which the contract reads instead of parsing error text.The built-in
agentmoves per-seat skills storage from org to user scope so two people do not share one worker’s drawer. Docs, kitchen-sink, and goal harnesses are updated (workerDoorhelper, Shift Manager EM inbox behavior).Reviewed by Cursor Bugbot for commit a657979. Configure here.