Skip to content

FIX-1502: the organization's inventory in the DevTool (ER-Devtool row 5) - #2147

Merged
jhoffner merged 8 commits into
mainfrom
fix/FIX-1502
Sep 24, 2026
Merged

jhoffner merged 8 commits into
mainfrom
fix/FIX-1502

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 24, 2026 •

Copy link
Copy Markdown
Collaborator

The problem

Someone running a hired workforce cannot find out, from the DevTool, who is in their organization: which seats exist, which channels exist, and who is in which. The app writes that inventory, but no browser read reaches it, and the only view is the debug panel, which is off wherever the app really runs. This is ER-Devtool checklist row 5, the last row W5 builds.

What this does

The three inventory collections now let a session read its own organization's rows, with named fields, through the ordinary collection route. The DevTool gains an Inventory tab on any session whose flow declares one of them: seats with their kind and channels, channels with their members and registration time, and memberships. Everything is labelled registered. A collection the flow does not declare reads not installed on this flow, and a refused read names its status; neither is drawn as an empty list. The multi-seat-collab lab gains the documented boot (open the channel, then the inventory), and the checklist goal gains a row-5 leg graded live with the debug endpoints off.

It does not add an organization picker, filter to seats that are working now, or wire the kitchen-sink's inventory.

What's asked of you

Nothing new. This implements the approved direction: D1 (the inventory becomes readable by the organization's own sessions) and D2 (row 5 means registered), both signed on 2026-09-24.

Parts worth reviewing closely

The rest of this is for whoever reviews the code.

  • packages/devtool/src/react/components/workspace/inventory-view.tsx + lib/inventory.ts: absent, failed and empty. Is there any path where a refused, failed or undeclared collection renders as an empty table? A wrong answer is the exact hollow state the row exists to prevent: an operator reads "nothing registered" when the read was refused.
  • goals/devtool-workforce-visibility/the-checklist-rows/row5.mts: step 6. Is "no debug read succeeded, and none was aimed at an inventory ref" the right reading of the plan's "no request under /debug/"? The shipped DevTool's own Resources panel asks /debug/resources on every session it opens, so a literal "no request" can never hold; the leg asserts that request is refused and the page reports debug disabled. A wrong reading lets rows read off the debug route pass.
  • goals/multi-seat-collab/lab/host.mts openLab: the boot now runs inside the served config, before the first request, and throws when openInventory reports a problem. FIX-1497's own check still drives the same lab; see below for its re-run.

Where I'm least sure: the manifest-read failure path. If the session's manifest read fails, the tab is hidden rather than shown with an error (a failed manifest leaves no way to say which collections exist). V3a proves the token is sent on the manifest request; the hidden-on-failure choice itself is a judgement call.

Deliberately not here: a row-6 leg (deferred by epic D11), a public inventory panel, the kitchen-sink's inventory boot (FIX-1455).

Spec (merged in #2138) · FIX-1502 · epic FIX-1457 W5 · merges on the owner's approval

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-1502/ 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 — decided along the way, no product sign-off needed
  • One PR, not the plan's three. The dispatch asked for a single implementation PR on fix/FIX-1502; the commits keep the plan's split (workforce, devtool, goals) so each can be read alone. Cost if wrong: a larger review surface than PR-A/PR-B/PR-C would have been.
  • The shared seam is a resourceClient on the DevTool context, built by createDevToolResourceClient(baseUrl, bearerToken) beside the session and recovery clients, so a credential change rebuilds it with the rest. Cost if wrong: a reader bypassing it would 401 in any app with a resolver (V3a is the guard).
  • The tab is hidden when the manifest read fails, not shown with an error: without the manifest there is no telling which collections exist. Cost if wrong: an operator on a broken session sees no tab rather than a named error; every other panel on that session fails visibly anyway.
  • A collection is "installed" when the manifest lists its pattern; the tab shows when any listed one is readable. A collection declared with no browser read is absent from the manifest by the engine's rule, so it reads not installed. With D1's read in the factories that only happens for a hand-declared collection on the same pattern (BR-3).
  • Three sections, including memberships, and the seat's Channels column comes from membership rows only (never the channel row's members), so BR-13's disagreement stays visible.
  • A read that fails after some pages shows the failure and the count, not the partial rows. A partial list reads as the whole one.
  • Row 5 runs on its own serve of the lab, debug off, in the same browser as row 4. Row 4's driver reads the ledger over the debug route, so one serve cannot hold both.
  • Step 6 reads "no request under /debug/" as: no debug read succeeded, none was aimed at an inventory ref, and the Resources panel reports disabled. The shipped Resources panel asks /debug/resources on every session, so the literal reading cannot hold on any DevTool build.
  • The lab's positive record reads the SQLite store directly (a second connection), never a route, so step 3 cannot share a fault with the screen.
  • BR-19 is graded on the refusal's message as well as its status, because the engine answers an unknown action with 500 DispatchFailed.
  • The "read removed" control reddens as "no Inventory tab", not "the tab names a 403" as the plan expected: the manifest omits a collection with no read. A second hand mutation (the channel collection declared with a content read only) produced the 403 in the served tab. Both are recorded in the goal's verdict log.
  • The spec's owner-decision citations now point at the epic's D10 (spec(epic): W5 amendment — Open 1 answered, row 6 carried, two proofs passed (FIX-1457) #2141 merged at 17:53Z), per PLAN's "At implement time".
  • The field lists (expose) are module-private constants, one per collection, naming every field the row schema declares today.
  • Changesets are minor for both packages: a published collection gains a browser read, and the DevTool gains a tab.
Everything else — verification, red states, the FIX-1497 re-run, files

CI is on the PR's checks; this block records what was run locally and the red states, which CI cannot show.

VG — the checklist goal, 2026-09-24, on 41eb55216: PASS: rows 4 and 5, graded on a live hire. Row 5 with FSDEV_DEBUG_ENDPOINTS=0: the store held exactly the tree's rows (3 seats, eng.queue with eng.planner, eng.builder, eng.reviewer, 3 memberships), a second boot changed none, the foreign organization's planted rows appeared nowhere, the tab showed every row equal to the store with nothing expanded and in view on both axes, each collection answered 200 on the production read, and the one debug request (the Resources panel's own) was refused 403. Row 6 not read live (epic D11). Full entry in the goal's verdict log.

Named controls, same commit:

  • no-inventory → FAIL (expected), row 5 only, at step 3: "the lab's organization holds no inventory rows, so there is nothing for the screen to show (the boot did not open the inventory)". Row 4 PASS.
  • silent-park → FAIL (expected), row 4 only, at the positive record. Row 5 PASS.

Hand-made reds on the row-5 leg, each reverted from a copy of the file:

Mutation Result
The browser read removed from the three collections step 4 "the channel's session eng.queue shows no Inventory tab", step 6 no 200 per collection
The channel collection declared with a content read only step 4 "the channels read was refused (403): State read not permitted for "channels". This is not an empty organization."
The view on the debug read, debug off step 4 (each section 403 debug_endpoints_disabled) and step 6 "the page asked the debug endpoint for the inventory"
The view on the debug read, debug on step 4 passes on the debug rows; step 6 alone fails: no production 200, a debug read served, Resources panel not disabled
The tab pushed 3000px down its pane step 5 "the seats row eng.builder is out of view vertically: 0px of a 29px cell can be seen", one per row
The route also reads the foreign organization step 4 "the tab lists 4 seat(s); the store holds 3", "another organization's "foreign-….seat" is on the page"
A channel that re-stamps openedAt every boot step 3 "a second boot over the same database changed the inventory"
seatWriter naming a kind that is not served the server does not start: "the lab's inventory did not register, so the lab will not serve: the seat rows could not be written — no flow is served under "no-such-kind""

Unit and integration checks (all green locally): @flow-state-dev/workforce 49 files / 773 tests (with the container's FSDEV_DEFAULT_MODEL/FSDEV_INTENT_* unset); @flow-state-dev/devtool 34 files / 359 tests; pnpm typecheck; pnpm knip:ci; the spec-folder, changeset-ref, model-string, NUL-byte, isolation-coordinate and publish-set validators.

Red states for the unit checks, each produced and reverted:

  • V1/V2/V5: the seat collection's client line removed → "org-a seat read — the manifest lists no such collection: expected -1 to be 200", "inventory/seats/ on a channel with the inventory on: expected undefined to be defined"*, V5 "expected 403 to be 200".
  • BR-5: the channel collection's expose removed → "a channels row must not carry "secret"".
  • BR-2/BR-4: the route's org read pointed at another org → "org-a's seats: expected [ 'beta.analyst', 'beta.lead' ] to deeply equal [ 'alpha.coder', 'alpha.lead' ]".
  • V3a: createDevToolResourceClient built with no fetcher (a bare client) → "the manifest request carries the token: expected null to be 'Bearer tok-inventory'".
  • V3b: an undeclared collection read as empty → "the channels section of a seat-only flow: expected 'loaded' to be 'not-installed'"; the absent text swapped for the empty text → "expected 'Registered channelsNo channels regist…' to contain 'Not installed on this flow.'".
  • BR-12: the channels heading changed to Open channels → "words the tab must not use: expected [ 'Open' ] to deeply equal []". The first cut of this scan read textContent and stayed green under that mutation (it glues "eng.queue" onto "Open"); it now joins text nodes with spaces.
  • BR-9/BR-10: a failed read returned as empty → "expected 'loaded' to be 'failed'" (403, later page), "… to contain '(404)'".

Docs: DOCS.md's three operations were published by an isolated docs-writer session (it read the public surface and DOCS.md only) and reviewed by an isolated docs-editor, whose verdict is the REVISE comment on this PR; its five fixes are applied verbatim in the last docs commit. Its two suspected inaccuracies: the limit range (1–200, default 50) matches the route; the pre-existing "one row per open channel" wording in the README table and the page's intro predates this change and is left for the epic-wrap docs polish. pnpm --filter @flow-state-dev/docs build exits 0 with no broken-link warnings.

FIX-1497's goal and its five named controls, re-run on 41eb55216: every behavioural leg moved exactly as its verdict log records and no further. The unperturbed run's only red is V7, and every control adds V7 beside its own legs (swapped-desks → V2; ignore-the-answer → V3; second-principal → V4; silent-park → VB screen 2; one-seat → V2 and V5). V7 is FIX-1497's own diff fence: it fails whenever the branch under test changes anything outside goals/ and specs/issues/FIX-1497/, so it is red on this branch (and on any branch touching packages/) by construction, not because the lab behaves differently. V0–V6 and VB are green.

Files: packages/workforce/src/inventory/collections.ts (the read); packages/workforce/test/cross-org-collection-read.test.ts (V1, V2, V5); packages/devtool/src/react/{lib/inventory.ts, components/workspace/inventory-view.tsx, lib/client.ts, context/devtool-context.tsx, DevToolPanel.tsx} and packages/devtool/test/inventory-view.test.tsx (V3, V3a, V3b) plus the panel mocks; goals/multi-seat-collab/lab/{host.mts, fsdev.config.mts, run-scenario.mts, README.md}; goals/devtool-workforce-visibility/the-checklist-rows/{row5.mts, run.mts, goal.md}; two changesets; specs/issues/FIX-1502/{DECISIONS,EVOLUTION}.md (D10 anchor); the docs pages listed in DOCS.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz

…X-1502)

The seat, channel and membership collections now carry
`client.state.read` with named fields (`expose`), the same shape the
hired roster already has. A session reads its own organization's rows
through the ordinary collection route; the organization is the
session's, never the request's. Prefix, scope, sharing and the
no-options signature do not move.

V1 (two organizations through the real channel kind and writer, with
the body/query/header, no-read and extra-key controls), V2 (the
manifest with the inventory on and off) and V5 (a fired seat is still
listed, today's behaviour) extend cross-org-collection-read.test.ts.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
…tion's inventory (FIX-1502)

The tab appears when the session's manifest lists any readable
inventory collection, found by its published key pattern. One section
per collection: seats with kind and channels, channels with kind,
members and registration time, memberships. A collection the flow does
not declare reads "not installed on this flow"; a refused or failed
read names its status and how far it got; neither is drawn as an empty
list. Every page is read. Every word says "registered".

Every request goes through a new `resourceClient` on the DevTool's
shared, bearer-aware client set. V3, V3a and V3b in
inventory-view.test.tsx; the panel wiring in devtool-panel.test.tsx.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
…oal grades row 5

multi-seat-collab's served config now runs the documented boot
in-process before the first request: the channel kind built with the
inventory on, `openChannels`, then `openInventory` under the lab's
organization, refusing to serve when it reports a problem.
`GOAL_CONTROL=no-inventory` skips the inventory half. The driver can
serve with the debug endpoints off and wait for the server to exit.

the-checklist-rows gains a row-5 leg (row5.mts): another
organization's rows planted first, the lab served with
FSDEV_DEBUG_ENDPOINTS=0, the store graded against the tree and across a
second boot before the screen, then the Inventory tab read by id with
nothing expanded, in view on both axes, over the production read.
goal.md records row 6's live read as deferred (epic D11).

Also: the spec's owner-decision citations point at the epic's D10, and
minor changesets for @flow-state-dev/workforce and @flow-state-dev/devtool.

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

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

Request Review

@linear-code

linear-code Bot commented Sep 24, 2026

Copy link
Copy Markdown

FIX-1502

@cursor

cursor Bot commented Sep 24, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot 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: serverGenReqId_d2c2b698-d09e-42c7-a350-055f6c8ee046)

@jhoffner
jhoffner marked this pull request as ready for review September 24, 2026 18:37
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 24, 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-24T18:45:35.576783Z da02b92 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.

…ol Inventory tab

- Live Inventory page: "From a browser" subsection under "Reading the
  inventory" (manifest lookup by pattern, paged listCollectionItems,
  org comes from the session, row fields, 404 on an unknown ref).
- workforce README: a short paragraph on the browser read after the
  inventory collections table.
- DevTool overview: new "Inventory" section after "Task boards".

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

Copy link
Copy Markdown
Collaborator Author

docs-editor verdict (FIX-1502):

VERDICT: REVISE

FINDINGS (most severe first)
1. packages/workforce/README.md:1493 — Unexplained internal (jargon)
   Quote: "Each row crosses with the fields in the table and nothing else."
   Why: "crosses" is boundary/wire vocabulary; a reader can't tell what crosses what, or why they should care.
   Fix: "Each row comes back with the fields in the table and nothing else."

2. apps/docs/docs/devtool/overview.md:151 — Unexplained internal
   Quote: "The tab appears on a session whose flow declares at least one of the three inventory collections with a browser read. Otherwise it isn't there."
   Why: "with a browser read" reads like a declaration option the reader has never been told about. They can't tell what they have to do to get the tab.
   Fix: "The tab appears on a session whose flow declares at least one of the three inventory collections." Cut "Otherwise it isn't there." If a flow-side setting really is required, name it and link to where it's set.

3. apps/docs/docs/devtool/overview.md:161 — Mechanism as reassurance
   Quote: "The tab reads through the same collection read your app's browser code uses, not the debug endpoint, so it works with `FSDEV_DEBUG_ENDPOINTS=0`."
   Why: The reader needs the consequence. "Not the debug endpoint" answers a question nobody asked.
   Fix: "The tab works with `FSDEV_DEBUG_ENDPOINTS=0`. Each request carries the DevTool's bearer token, …"

4. apps/docs/docs/workforce/inventory.md:202 — Mismatch with the example
   Quote: "pass `nextCursor` back as `cursor` until it comes back empty."
   Why: The example above loops until `nextCursor` is `undefined`. "Empty" makes a reader wonder whether to check for `""` too.
   Fix: "until `nextCursor` is undefined."

5. packages/workforce/README.md:1492 — Terminology drift (minor)
   Quote: "from any session whose flow installs them."
   Why: The docs page and the DevTool section both say "declares". Two verbs for the same act makes the reader wonder whether they mean different things.
   Fix: "whose flow declares them."

SUSPECTED INACCURACIES
- packages/workforce/README.md:1486-1487 vs :1494 — The table heading says "One row per … open channel", and the section intro says the inventory answers "what is open right now". The new paragraph says "A row means the seat or channel was registered: nothing is removed". inventory.md:206 says "registered, not open". The table and intro now contradict the added text. The writer should verify which is true and reconcile.
- apps/docs/docs/workforce/inventory.md:202 — "`limit` takes 1 to 200 and defaults to 50" is not shown or used in the example. I can't check it from here. Please confirm against the client API.

OFFERED CONTEXT DECLINED
- None offered. Spec, PR body, commits and implementation diff were not read, per the brief.

Generated by Claude Code

@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: da02b92058

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

…led read (FIX-1502)

A server that keeps returning a nextCursor would have held the
Inventory tab in its loading state forever. The read now stops at the
same 1000-page bound the shipped panel readers use, and on a cursor it
has already seen, and the section names why instead of showing rows or
an empty list.

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