Skip to content

ER-Collab: two seats hand a row over, and you can watch it in the DevTool (FIX-1497) - #2065

Merged
jhoffner merged 11 commits into
mainfrom
fix/FIX-1497
Sep 22, 2026
Merged

jhoffner merged 11 commits into
mainfrom
fix/FIX-1497

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 22, 2026 •

Copy link
Copy Markdown
Collaborator

The problem

W5 is done when three exit proofs pass. ER-Collab is the one that decides whether "two seats can work a shared channel, stop to ask a person, hand work over — and you can see it happen" is a claim or a fact. Every piece existed; nothing had ever run them as one scenario, and nobody had watched work change hands. The human leg — a seat stopping on a question and a person answering it — had never run on a hired workforce at all.

What this does

A new lab, goals/multi-seat-collab/, and one goal check that drives it. Three seats hired from Markdown (a planner and two workers) share one channel's board, served by the ordinary fsdev dev:

  1. The planner files one piece of work for the build desk.
  2. The seat whose own file answers for build takes it, hits a question only a person can settle, and parks the row saying what it needs.
  3. The person answers through that seat's own action. The same seat finishes the row and, in finishing, files the next row for the review desk.
  4. The other seat takes that row and finishes it.

Then a real browser opens the shipped DevTool and reads it on three screens, one click apart: the seat's Tasks tab (the row and a link to where it ran) → that session's Tasks tab (why it waited, then what it was told, with nothing expanded) → the Resources panel's ledger (both rows, both desks, which seat ran each). Nothing was built to make the inspection possible.

How the lab is wired: the Markdown tree on disk, the lab's code (host.mts, the planner and worker kinds under flows/workers, the driver), and what runs (fsdev.config.mts with the app's desk-to-seat map, the shipped fsdev dev, the shipped DevTool); the person's answer enters only through the owning seat's own answer action.

Left to right: files on disk, code, what runs. Routing comes only from the app's map in the config — each WORKER.md's desk is what the checks grade against — and the person has one door, the owning seat's answer action.

One run as four lanes against time — eng.planner, eng.builder, the person, eng.reviewer — with the check that grades each step, and below them the three DevTool screens that read it, all graded by VB.

The crossing from eng.builder's lane to eng.reviewer's is the handoff, a second row on the same board; each step carries the leg that grades it.

It has been run, and it passes. The graded run waited on ER-26 until FIX-1496's #2051 merged; this branch was brought up to that main and run, and the verdict log carries a dated PASS on the current checks. Every claim has a control that makes it go red, and every control has been seen red at exactly the leg it names. Nothing under packages/ changes.

What's asked of you

This implements the approved spec. Nothing here needs a sign-off. DOCS.md records no reader-facing change, so there is nothing to publish now that the graded run has passed.

Parts worth reviewing closely

  • When the park is proved. The seats hand rows off to a child session, so the drain that claims the row finishes (handed-off) before the row parks. BR-6's "the drain returns and the row stays parked" is therefore graded on the next drain over the parked row, which must return parked-for-review with the row still parked. The spec assumed the first drain would say it; with hand-off it can't.
  • The worker reaches its row through the board's own capability (lab/workforce/flows/workers/worker.mts, uses: [board.capability]). An earlier draft built its own reference over the raw ledger and the assignee move BR-14 must see refused was accepted — a hand-built reference skips the board's frozen-assignee policy. Worth a glance from anyone who knows that policy.
  • The second answer's verdict is read off the request's own recorded output (actionOutputOf in run-scenario.mts): the HTTP action route returns no output, so BR-10's declined / terminal is read from the root block trace the DevTool's Trace tab renders.
  • The second-principal control is driver-side. Nothing under packages/ may change, so the control sends the "second person's" answer as the owner instead. It proves the leg can see a landing; the unperturbed run is what shows a second person's answer does not land.
  • Screens grade against the ledger, not against the story. VB checks that what a person sees matches what the ledger holds; whether the ledger holds a real handoff is V5's. That split is what lets each control redden exactly one leg (two, for one-seat, as the plan requires). It matters on screen too: the child session's own Tasks tab still lists the review row as pending, because its last change there was the add — where both rows are now is the ledger's to show (BR-17a).
  • A long question is clamped to its column and whole on hover (FIX-1481's design). The check grades the hover text when the cell is clamped rather than passing on text nobody can see.

FIX-1497 · epic FIX-1457 · spec specs/issues/FIX-1497/ (approved, merged #2045) · graded run after #2051 · related FIX-1511 · merges when approved; implementation merge is a human's call

How to review this — altitude, what's in scope, what's deliberately unsettled

How to review this. This implements an approved spec — the approach and the numbered decisions in its DECISIONS.md are already signed off by a human, so please review the code against that direction, not the direction itself. The canonical set is retained at specs/issues/FIX-1497/ on main; Linear links to it and the original merged spec PR, which keeps review history. Follow-up amendment PRs explain later direction changes. Current architecture docs remain the authority for shipped behavior (BP-037).

Most valuable here: correctness on the second path (the legacy shape, the null boundary, the concurrent case, the cancel path), anything deriving an auth or routing decision from caller-controllable input, and a behaviour the tests assert around rather than on.

Already settled upstream: the approach and every decision in the spec's DECISIONS.md (human-approved — if one is wrong, say so as a spec finding and it gets folded back; don't re-argue it inline), and the conventions in docs/contributing/best-practices.md.

Engineering calls
  • A second person's answer does not land, per ER-1; today it doesn't land by hanging, not by an explicit refusal. The request is admitted (202) and never settles, with nothing logged. That is FIX-1511's to fix (an engine change BR-19 fences out of here); this PR adds the evidence — an ordinary wrong-user request triggers it, commented on FIX-1511. V4 counts a 202 with a request id, or an explicit 401/403 recorded as a refusal; any other status, a missing request id or a transport error fails it.
  • BR-6 on the next drain, as above — the claiming drain's own reason is recorded in the run's notes (handed-off) rather than asserted.
  • The claim record for BR-8 comes from two places. A task board's change items are keyed per row within a request, so a claimed item is overwritten when the same request later records another change for that row. So every claim is graded on the row's own claimedBy, read from inside each attempt (it must be the running seat's own session), and the row for nobody — which never reached an attempt — must have a claim or refusal on record from a seat's own drain.
  • BR-7's "the answer runs the work" is graded on the finishing attempt's claim: it must have been made by an answer request on the owning seat's session, not by a later drain that happened by.
  • One file per kind under lab/workforce/flows/workers/ (planner.mts, worker.mts), as the sibling labs do. The row's input contract both share sits beside them in lab/workforce/flows/piece.mts, not under flows/workers/, where a file reads as a kind.
  • The tree is refused unless it is exactly one planner and two workers — a stray seat would still hire and drain.
  • The handoff row carries input: { follows: <first row id> } and is added by the finishing seat through the board, not through the channel's fileTask door.
  • One switch, end to end: GOAL_CONTROL is read by both the check and the server's config (the POC's two variable names were a review note).
  • as never on defineFlow / hireWorkforce / createFlowState stays, as in manager-queue-lab's kind factories.
  • Stores are SQLite under the server's scratch directory, the shape fsdev dev builds when it discovers flows itself.
  • The dated VG row replaces earlier ones as the checks changed; it describes the checks as they stand.
  • No changeset: goals/ is private and nothing published changes.
Everything else — surfaces, checks, verification

Surfaces (PLAN S1–S7), all under goals/multi-seat-collab/: lab/workforce/ (the POC's tree, unchanged, plus flows/workers/planner.mts, flows/workers/worker.mts and flows/piece.mts) · lab/host.mts (read, refuse whole, hire; the map is an argument) · lab/fsdev.config.mts (what fsdev dev serves; the app's desk → seat map) · lab/run-scenario.mts (spawn, open the channel through openChannels over HTTP, file / drain / answer) · lab/diff-check.mts (the fence) · lab/figures/ (setup.svg, flow.svg) · it-hands-a-row-between-two-seats-in-view/ (run.mts, goal.md, fixtures/input.json) · lab/README.md.

Checks: V0–V7 and VB are legs of one run, each failure tagged with its leg; controls grade themselves. goal.md has the contract and the verdict log.

Verification on this branch:

  • VG: pnpm tsx goals/multi-seat-collab/it-hands-a-row-between-two-seats-in-view/run.mts — PASS on every leg, on the current checks, on the branch merged with the main that carries The DevForce exit proof ships a real artifact, and it has been run (FIX-1496) #2051; recorded in the verdict log.
  • GOAL_CONTROL=swapped-desks → V2 only · ignore-the-answer → V3 only · second-principal → V4 only · silent-park → VB only · one-seat → V2 and V5. Each recorded in the verdict log with what it printed.
  • The five checks hardened after review were each reddened alone by hand and reverted: a decline mapped to unchanged → V3; the orphan's seat record dropped → V4; the screen-3 body locator pointed at nothing → VB; a third WORKER.md → refused before any leg; a simulated 500 for the second person → V4.
  • V0 / V6 / V7 reddened once by hand (a file holding the minted id; a status dropped from the written list; a file under packages/), then reverted.
  • The two figures were rendered in both themes in headless Chromium and inspected; they carry no minted ledger id, and V0 and V7 pass with them in place.
  • goals typecheck clean; pnpm knip:ci clean; validate-model-strings, validate-no-nul-bytes, validate-spec-folder clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz

A sibling lab under goals/multi-seat-collab/: a planner and two worker
seats hired from Markdown work one channel's board on the shipped
fsdev dev. The owning seat parks a row with its question, a person
answers through that seat's own action, the same seat finishes and
files the next row for the other desk, and the other seat runs it.
The goal check drives it over HTTP and reads it in Chromium on the
shipped DevTool: the seat's Tasks tab, the child session's reason with
nothing expanded, and the ledger collection with both rows.

Five controls, each graded against the legs it names. Nothing under
packages/ changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
Trimming the whole status output ate the first line's leading status
column and shifted its path by one character.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
Every named control was run on 2f2e86a and went red at exactly the
legs it names; V0, V6 and V7 were reddened once by hand and reverted.
The graded run is not recorded: it waits on a live hired Workforce,
which #2051 stands up and which has not merged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
@vercel

vercel Bot commented Sep 22, 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 Sep 22, 2026 9:29pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 22, 2026 9:29pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 22, 2026 9:29pm UTC

Request Review

@linear-code

linear-code Bot commented Sep 22, 2026

Copy link
Copy Markdown

FIX-1497

@jhoffner
jhoffner marked this pull request as ready for review September 22, 2026 20:45
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 22, 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-09-22T20:53:59.522880Z 4abf485 Draft marked ready
ℹ️ 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.

@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 review (FIX-1497)

Read the full diff (~3.2k lines, goals/multi-seat-collab/ + retained spec/POC). Parallel passes looked for unnecessary abstraction, duplication, and simpler alternative architectures.

Verdict on the approach

The served fsdev dev + HTTP driver + separate kinds.mts / fsdev.config.mts split is the right shape for what this issue proves. An in-process lab like manager-queue-lab's openLab() would be materially smaller, but it would not exercise the ordinary dev server, intent-free env (FIX-1511), or the DevTool legs (VB/VG). Folding that into one process would trade proof strength for line count — I would not recommend it without a spec change.

The retained POC under specs/issues/FIX-1497/poc/ is heavy (inline flow logic + a second copy of the workforce tree), but it is documented as evidence, not something to copy. That is acceptable for a spec PR; the publishable surface is the lab + goal.

Approval is on direction: the complexity here mostly buys real fences (served path, outbox oracle, controls, DevTool visibility), not framework churn in packages/.

Where the change went further than necessary (non-blocking)

These are hygiene / follow-up items, not merge blockers:

  1. goals/lib scaffolding duplicated again — serveLab (~run-scenario.mts) closely mirrors specs/.../poc/served-hire-observable/check.mts (tsx spawn, random port, intentFreeEnv, health poll, child-exit guard). Same story for preinstalledChromium() (verbatim vs goals/flow-instances/devtool-shows-the-selected-copy/run.mts), recursive treeFiles, DevTool build:assets, and most of diff-check.mts vs manager-queue-lab. A small shared module (serve-fsdev.mts, playwright.mts, listFilesRecursive, parameterized merge-base fence) would shrink the next DevTool goal more than this PR needs to grow.

  2. Identical workforce/ in lab and POC — diff -qr shows no differences. One canonical tree under goals/multi-seat-collab/lab/workforce with the POC defaulting to that path (or a CI sync check) avoids silent drift.

  3. run.mts at ~587 lines — Headless legs (V0–V7, controls, oracle) and Playwright (VB) share one main(). Extraction of browser-only helpers would help readability; splitting headless vs browser drivers is optional unless more collab goals appear.

  4. Type escape hatches — as never on defineFlow / hireWorkforce and ctx.cap as unknown as Record<...> for tasks() hide whether the lab is fighting framework types. Worth a quick experiment to narrow types once; might be unavoidable today.

  5. Lab-local HTTP any — Scenario bodies use loose shapes; fine for one goal, brittle if copied. Partial @flow-state-dev/client adoption only where it matches debug routes.

  6. Comments vs README — Module headers largely restate lab/README.md / goal.md. Trimming to API + traps would reduce drift surface (style, not correctness).

Simpler alternatives considered

Alternative Why weaker here
Reuse openLab in-process only No served DevTool / BR-15–17 path
Drop NDJSON outbox oracle; assert board only Weakens anti-game controls in goal.md
Merge POC into lab dispatcher Violates retained-evidence boundary
Third-party for browser Already Playwright; appropriate

Performance (lab scale only)

appendFileSync in runRow, idlePollMs: 25, and 50ms HTTP polling in act / waitForRow are fine for this scenario. Only worth revisiting if this pattern becomes a template for many seats or long runs.

Optional follow-up

If you touch this again before VG un-fences on #2051, the highest leverage simplification is goals/lib serve + Playwright + tree listing and one workforce tree — not restructuring the lab's orchestration model.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

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

Code Snob — already tight. No POC.

Read goals/multi-seat-collab/lab/kinds.mts, host.mts, fsdev.config.mts, run-scenario.mts, diff-check.mts, it-hands-a-row-between-two-seats-in-view/run.mts, and the four workforce files, against PLAN S1–S7 on head 4abf485.

A rewrite would not shrink the contract. The two kinds, the caller-supplied desk map, the HTTP driver, and the nine legs are the surfaces the plan names. Inlining file / drainAll / answer into the check, or folding the three screens into one helper, moves the same assertions. deskDispatcher and the outbox line are the sibling shape the plan says to take, and every field on that line except goal is read by a leg. LAB_DIR is an unused export. Neither is a smaller hire. The hand-rolled fetch is shorter than adapting @flow-state-dev/client: that client binds userId and throws on a non-202, and V4 has to see both.

Not re-opened: grading BR-6 on the next drain, two claim sources, GOAL_CONTROL as the one switch, as never matching the sibling factories.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@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: 4abf4851e3

ℹ️ 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 goals/multi-seat-collab/lab/host.mts Resolved
- BR-10: the second answer must come back declined as terminal, read
  from the answer action's own recorded output.
- V4: the row for nobody must have a claim or refusal on record from a
  seat's own drain, not just an errored status.
- V4: a second person's delivery passes only as a 202 with a request id
  or an explicit 401/403; any other status or a transport error fails.
- VB: a listed ledger row whose expanded body shows nothing fails
  screen 3 instead of being skipped.
- BR-1: the tree must hold exactly one planner and two workers.

Also drops the unused LAB_DIR export.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
VG passes on 6a2b33c. Each named control still reddens exactly its
legs; each of the five hardened checks was reddened alone by hand and
reverted. The verdict rows now describe the checks as they stand.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
* wrong one.
*/

import { defineFlow, dispatcher, handler } from "@flow-state-dev/core";

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.

kinds should be declared within flows/ not as a single kinds file

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.

Done in 6409f7f00. kinds.mts is split into one file per kind: lab/workforce/flows/workers/planner.mts and worker.mts, each basename matching the kind a WORKER.md names in its flow: line, as devforce-lab does. The row's input contract, which both kinds use, sits beside them in lab/workforce/flows/piece.mts rather than in flows/workers/, because a file there reads as a kind.

It's a move with no behaviour change:

  • The loader doesn't walk flows/. The tree read and the scan for the minted ledger id both pass with the new files in place.
  • VG passes on 6409f7f00.
  • All five controls fail at the same legs as before.

The verdict log is updated in 54b81d015.


Generated by Claude Code

…kers

planner.mts and worker.mts, basename = the kind a WORKER.md names, as
devforce-lab and manager-queue-lab do. The row's input contract both
kinds share sits beside them in workforce/flows/piece.mts, not under
flows/workers/, where a file reads as a kind. A move: no behaviour
changes, and the loader does not walk flows/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
VG passes on 6409f7f; every control reddens the same legs as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
@jhoffner

Copy link
Copy Markdown
Collaborator Author

Please provide SVGs that detail how the lab is setup to work and flow, so we can document. Reference those SVGs within the PR description

setup.svg: the Markdown tree, the lab's code and what runs, with the
person's one door. flow.svg: one run as four lanes with the check that
grades each step, and the three DevTool screens that read it. Both are
self-contained, both themes, referenced from the lab README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz

Copy link
Copy Markdown
Collaborator Author

Re your figures request (comment 5784314186): added in 9cf85c836, under goals/multi-seat-collab/lab/figures/:

  • setup.svg, how the lab is wired. Left to right: the Markdown tree (CHANNEL.md with boards: [work], and the three WORKER.md files with their desks), then host.mts and the two kinds in lab/workforce/flows/workers/, then fsdev.config.mts with the app's ROUTES map, the shipped fsdev dev and the DevTool. It also marks the person's one door: the owning seat's answer action.
  • flow.svg, how a run moves. Four lanes: file → drain and claim → park with the reason → answer through eng.builder's action → finish and file the review row → eng.reviewer finishes it. Each step is labelled with the check that grades it (V1–V5). Underneath are the three DevTool screens that read it, graded by VB.

Both figures are embedded in the PR description, pinned to that commit, and referenced from lab/README.md. Each renders in both light and dark themes; I checked both in headless Chromium. Neither contains the minted ledger id, and V0 and V7 still pass with them in place.


Generated by Claude Code

@jhoffner
jhoffner merged commit 3d99393 into main Sep 22, 2026
12 checks passed
jhoffner pushed a commit that referenced this pull request Sep 22, 2026
jhoffner pushed a commit that referenced this pull request Sep 24, 2026
FIX-1497's spec still described its graded run as fenced by ER-26. The
fence lifted on 2026-09-22 when #2051 stood the live hire up, and the
graded run passed (#2065). Dated in place, history kept, the same way
FIX-1496's lines were:

- PLAN.md:8 — "The run is fenced; the build is not"
- BUSINESS-RULES.md:73 — BR-21 "It waits on a live hired Workforce"
- DECISIONS.md:69 — "ER-26 still fences the graded run"
- DECISIONS.md:83 — "the run is already fenced until a live hire exists"

PLAN.md:203 was already dated and is unchanged.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
jhoffner pushed a commit that referenced this pull request Sep 24, 2026
…eaches the prompts

Review on #2167, two findings:

- Per-assertion alone passes vacuously when an assertion is missing, and
  two of the ten cited instances were exactly that (#2065's decline,
  #2051's completed-over-rejected row). The same sentence now also says
  every outcome the leg claims maps to an assertion.
- The rule has to reach what is dispatched. One line each mirrors it into
  the Step 6 completeness gate, implementer-prompt.md and
  spec-reviewer-prompt.md. No new section.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants