Skip to content

spec(FIX-1788): A worker is a private resource its owner holds, run by the shared flow it names - #2812

Merged
jhoffner merged 2 commits into
mainfrom
spec/FIX-1788
Oct 6, 2026
Merged

jhoffner merged 2 commits into
mainfrom
spec/FIX-1788

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 6, 2026 •

Copy link
Copy Markdown
Collaborator
Someone who… Today After
shares an org with other users A worker that someone hired for the org is open to every member. Any member can open a session on it Each worker belongs to one user. No other user can open, read, run or link a session to it
hires or fires a worker while the app runs Other processes see the change only after they restart The change is a data write. Every process sees it on the next turn
wants their own version of a standard worker Edits the file and restarts, for all users Forks it. The fork is theirs. No user can change a standard worker at run time
builds an app that talks to a worker Sends to the worker's own copy, at acme.~alice.researcher Sends to the flow (agent) and names the worker. The server links the session one time
upgrades a deployment that has hired workers n/a One operator step moves each hire, its memory and its conversations to its owner. The step deletes nothing

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

flowchart LR
  S["one app · two users of one org · two processes on one store"] --> A["leg a · Alice forks, hires, talks"]
  S --> B["leg b · Bob reaches for Alice's workers"]
  O["a store today's main wrote"] --> C["leg c · the upgrade step"]
  A -->|"one copy per flow · own memory · seen without restart"| P["PASS · the goal is met"]
  B -->|"refused every time"| P
  C -->|"each hire with its owner, nothing deleted"| P
  X["control · workers at org scope"] -.-> B
  B -.->|"under the control"| F["must FAIL · Bob reads Alice's worker"]
Loading

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-workers and GOAL_CONTROL=caller-link. Why this goal and not a smaller one: SPEC.md.

Today each hire registers its own copy of a flow; after, one copy per flow, a worker is data, and a session names its worker one time

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

Q1, open: a copy, recommended, beside follow the standard worker. Decides it: nothing changes under the owner. Price: forks go stale until the owner forks again

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

D1: one operator step, chosen, beside reading the old shape at run time. Decides it: the old per-worker copies go after one run. Price: old hires wait for the operator

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

D2: a copy for each member who used it, chosen, beside nobody's until an operator names one. Decides it: what each person already had. Price: one worker becomes several

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

  • Plan → S8 and S7. A shared copy has one resource map. Can document grants and per-worker memory hold on each turn with no engine change? If not, the work goes back to the epic.
  • Rules → BR-10 to BR-19. Does every path that opens a session pass the one link check: a person's turn, a task, a mailbox post?
  • Plan → the PR plan. No existing flow changes shape before the upgrade step is on 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:

  • 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.
  • A case BUSINESS-RULES.md misses, or a rule that would invalidate the design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.
  • The reader-facing promises in DOCS.md and their fit with the rules; a missing or
    misleading lineage claim in conditional EVOLUTION.md.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • Names, signatures, file paths, and module layout beyond the few PLAN.md pins on purpose.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Micro-optimizations and style preferences.
  • Test names and internal test structure (the behaviours are the rules; the tests are not).
  • Anything PLAN.md left open on purpose — it is directional by design, and a gap at that
    altitude is intended, not an omission.
  • 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.
  • The solution sketch, at the line level. PLAN.md may include a rough pseudocode sketch
    showing 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 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 PLAN.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 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
  • The link lives in session state that the flow declares server-owned (the epic's D3, change 3). The session create refuses caller state for it.
  • The link is set on the first turn, after one check: the worker is the user's own or standard, it names this flow, and the session has no link. It never changes.
  • A worker's configuration is read on each turn, with names resolved against what the installation registers. A non-standard worker is checked on save and on load.
  • A worker's private state is keyed by the worker on every worker flow, the skills drawer first.
  • Document grants and the reference wall narrow what the worker's model reaches on each turn.
  • A worker id is unique on its owner's roster and cannot be a standard worker's id.
  • Fork and the library's copy share one write path. A fire deletes the row; its sessions stay readable.
  • The upgrade step ships as code, not a SQL procedure.
  • Four PRs in a stack: server-owned state; the worker model beside today's; the upgrade step; the switch.
  • No worker-flow declaration shape is named. The agent change takes either shape.
POC — which flows the switch converts
node specs/issues/FIX-1788/poc/flow-inventory/inventory.mjs                    # PASS: 23 flows over 94 WORKER.md files
CONTROL=drop-one node specs/issues/FIX-1788/poc/flow-inventory/inventory.mjs   # must FAIL, exit 1

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

…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
@jhoffner jhoffner added the spec label Oct 6, 2026 — with Claude
@vercel

vercel Bot commented Oct 6, 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 6, 2026 7:50pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 6, 2026 7:50pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 6, 2026 7:50pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 6, 2026

Copy link
Copy Markdown

FIX-1788

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 6, 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-06T19:45:18.987719Z 8fac75c PR opened
ℹ️ 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.

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

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)

  1. Org-wide fan-out in the upgrade step (PLAN.md S13, DECISIONS.md D2, BUSINESS-RULES.md BR-30/31). Confidence: Low; severity: Med; about −150 lines (est.).

    • Carrying every org-wide hire across to each member is the most intricate part of S13: per-member session discovery, a cell copy per member, and an id-collision path.
    • Nothing in the spec shows an org-wide hire in use other than the CoS seat from FIX-1719.
    • Suggestion: carry owner-held hires only. Report org-wide rows and leave them, and re-hire per user on demand.
    • This is already a sign-off item. The question for that gate is whether any real deployment has an org-wide hire people use today. If none does, take D2's "nobody" branch; if one does, keep D2.
  2. Deprecation markers in S2 (PLAN.md S2, BR-27, V2). Confidence: Med; severity: Low; about −45 lines (est.).

    • FIX-1798 deletes the pin and cardinality surface in the same epic. The markers and their tests would be added in P1 and then deleted again.
    • Suggestion: drop S2 and V2 from P1.

Architecture opportunity (improve-codebase-architecture)

  1. Make S5 + S6 one deep module with one interface.
    • S5 (the link check and write) and S6 (load the linked worker each turn, resolve names, refuse unresolved) are listed as separate surfaces. S6 also takes over every read of a worker setting from ctx.flow.config.
    • Callers (the door, the task entry, the mailbox wake, and each setting read inside a turn) should reach one narrow interface, roughly resolveWorker(ctx) → { worker, resolved config } plus link(...). They should not touch the worker row, the name resolution, or the refusal rules.
    • This gives locality: BR-19, BR-20, BR-22 and "broken worker refuses at load" live in one place, and tests go through the interface instead of per-consumer.
    • The deletion test says the module earns its keep, because S11's three consumers and the ctx.flow.config sweep would otherwise each re-derive it.
    • This is a localised change with no change to docs/architecture/* contracts. It only affects how P2 is cut: add one line to S5/S6 so the implementer treats it as one module, and keep the ctx.flow.config migration behind it.

Considered and left alone

  • fork as its own block: it is the single write path the library copy (FIX-1795) shares.
  • S7/S8: they replace guarantees that exist today (per-copy resource map and drawer), so they are required work.
  • S11's mailbox wake path: skipping it would leave an open hole in the "every path through one check" guardrail.
  • poc/flow-inventory/: V0 reruns it as a gate before P4, so it has a consumer.
  • The figures: spec-figures.md requires them.

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.

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.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1788/DECISIONS.md Resolved
Comment thread specs/issues/FIX-1788/PLAN.md Resolved
Comment thread specs/issues/FIX-1788/DOCS.md Resolved
Comment thread specs/issues/FIX-1788/BUSINESS-RULES.md Resolved
Comment thread specs/issues/FIX-1788/PLAN.md Resolved

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

Comment thread specs/issues/FIX-1788/BUSINESS-RULES.md Resolved
Comment thread specs/issues/FIX-1788/BUSINESS-RULES.md Resolved
Comment thread specs/issues/FIX-1788/PLAN.md Resolved
Comment thread specs/issues/FIX-1788/BUSINESS-RULES.md Resolved
Comment thread specs/issues/FIX-1788/BUSINESS-RULES.md Resolved
Comment thread specs/issues/FIX-1788/BUSINESS-RULES.md Resolved
…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 })

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 })
  • getWorkerSession derives the flow from the worker's own configuration, so the app never names agent.
    • 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.
  • The returned handle is bound to one session. sendAction(action, input) carries no flow, no worker and no sessionId.
  • 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

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ships worker, FIX-1794 adds taskId, and FIX-1793 adds workstreamId, 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 still createSession({ …, 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

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 through createSession({ 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 ensureWorkerSession calls 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" }). Show findWorkerSession where an app only wants to check.

Generated by Claude Code

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

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):

  • Codex: standard-only flows on save, on load and in the step (BR-6, BR-22a, BR-33a). writtenBy stamped from the link (BR-25a). The first-turn link is atomic per session (BR-13a). The step copies org-wide memory (BR-30) and renames a moved worker on an id collision instead of skipping it (BR-31).
  • Narrowed: a session whose flow is no longer registered reads the way it does today (BR-19a), with no new engine read path.

Review comment from the owner's account, item by item:

  1. Org-wide fan-out. This is D2's fork and stays on the sign-off. D2's What would change my mind now names the fact that decides it: whether any deployment uses an org-wide hire today besides the chief-of-staff seat. If none does, D2 takes the "nobody's" branch and the step only reports those hires. That would also remove BR-30 and BR-31's per-member copy, along with the memory copy and the rename folded above.
  2. Drop the S2 deprecation markers. Dropped. FIX-1798 is outside this epic (epic ER-20), and the epic's approved D3 assigns the markers to this issue: "Flow instances and owner pins get deprecation markers, nothing more". The markers stay until FIX-1798 actually lands.
  3. S5 and S6 as one deep module. Noted for the implementer, verbatim, in PLAN.md → Notes from review. It changes how P2 is structured inside, not its shape.

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

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering / session: em-fix-1786 / kind: decision

Round-2 fold checklist for this spec, gathered in one place:

  1. The worker link is set at session create, not on the first turn (thread on SPEC.md L67). Rework Decided, not asked, BR-10 to BR-14, BR-13a (racing first turns becomes racing creates, or drops), S5, V4 and DOCS to match. The epic records it in spec(epic): record Q1 (the list), no engine rule on org scope, worker link set at create (FIX-1786) #2813 as D3 change 3's session-record form.
  2. Show the whole app flow on today's client (same thread, the superseding reply): read the roster (worker.flow), then listSessions({ …, worker }) or createSession({ …, worker }), then createClient({ flowKind }).sendAction(action, input, { sessionId }). Pin only worker on create, worker on list, and the roster's flow.
  3. The mechanism must also hold a coordinator's delegates. They change after create, so a create-time field alone isn't enough. Name a mechanism that holds both: the immutable create-time link, plus server-written state that can change. FIX-1791 confirms it.
  4. Existing sessions when their worker changes:
    • Edited to name a different flow: the link holds, and the per-turn load refuses the turn because the worker no longer names this session's flow.
    • Forked: the fork is a new worker, and old sessions stay with the original.
    • Fired or flow removed: BR-19 and BR-19a, as now.
    • The epic's ER-1 points here.
  5. "Seat" is retired (Jake on spec(FIX-1790): A user's data is kept per org, for every flow #2810). DOCS.md still teaches createSeatHireBlocks and has a "hired seats" heading, and DECISIONS L57/L85 say "seat" in prose. Draft docs use the new names now, not at P4. EVOLUTION rows quoting earlier decisions can stay.

Generated by Claude Code

@jhoffner

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

I agree with the recommendations

@jhoffner
jhoffner merged commit ab52aa8 into main Oct 6, 2026
13 checks passed

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

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"):

  • Q1 is decided: copy. A fork copies a standard worker's shared instructions at fork time. Following later edits can come later as an opt-in. Move Q1 from Open to Decided in DECISIONS.md, with the reasoning and what lost.
  • D1 is signed: old hires move in one operator step.
  • D2 is signed: an org-wide hire is copied to each member who used it.

The round-2 fold carries these alongside the checklist above. The merge waits for the round-2 head.


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants