Skip to content

fix(engine): list a seat's sessions and runs to the caller its own resolver accepts (FIX-1566) - #2192

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

jhoffner merged 8 commits into
mainfrom
fix/fix-1566

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 24, 2026 •

Copy link
Copy Markdown
Collaborator

The problem

An operator hires a seat that checks callers with its own credential. With that credential they can open the seat's sessions and run its actions, and since #2184 they can see the seat in the flow list. But the session list and the list of in-flight runs never show them that seat's sessions or runs.

Those two lists only ask the app-wide sign-in who the caller is:

  • In an app where only some flows authenticate, they drop every row of a flow that has its own check.
  • In an app with an app-wide sign-in, they compare every row to the app-wide user, and a seat's operator is a different person.

Nothing leaks today. The lists just come up short.

What this does

For each row in the two lists, the engine now asks the flow that owns the row who the caller is, the same way opening that flow's session does. The row appears only when all three hold:

  • that flow accepts the caller;
  • the row belongs to the person it names (user and organization);
  • if the seat is pinned, its pin admits them.

Each seat is asked on its own, so one seat's credential never shows another seat's rows. Rows of flows with no check of their own follow the same rules as before. A caller with no credential still sees the open flows' rows and gets a 200, not a 401.

Behaviour change for apps with an app-wide resolver

A row that belongs to the app-wide user is now hidden when the seat it lives on refuses that user. Before this change such a row was listed.

  • Who it affects: apps that set a host-level resolvePrincipal and also have flows (such as hired seats) with their own resolver.
  • What they'll notice: the app-wide user no longer sees, in the session list or the active-requests list, rows from a seat whose own resolver would refuse them.
  • Why it's right: the list now agrees with the doors. get_session on that row already resolves through the seat's resolver and refuses the same caller, so the old listing showed rows the caller couldn't open.
  • Unchanged: a caller the app-wide resolver itself refuses still gets 401 on both listings, whatever a seat would say.

What's asked of you

Nothing here is yours to decide. This is a bug fix, and the PR is the review surface. Land #2191 before or with this one. It fixes the kitchen-sink tests that main currently fails, and its branch is merged in here (65d0bdd) so CI runs against a green base.

Parts worth reviewing closely

  • packages/engine/src/routes/session-routes.ts → handleListSessions.
    • With an app-wide resolver, the store query stays scoped to the app-wide principal unless some seat's resolver names the caller as someone else.
    • Only then does it run unscoped and filter each row, so pages can come back shorter than limit, as the anonymous listing's already can.
    • Check the scope decision, and that the userId query param can still only narrow the result.
  • packages/engine/src/routes/instance-caller.ts → ownResolverVerdict.
  • The tenant check in both listings (67e8085). It runs on every row before either verdict.
  • The behaviour change above.

Linear: FIX-1566 · Epic session: epic/FIX-1528 · Builds on #2184 · Bug route, no spec · Merges.

How to review this — altitude, what's in scope, what's deliberately unsettled
PR kind The one question The human judges Automated review helps most on Do not report
Implementation PR (fix/<ISSUE-ID>, merges) Is this correct, and does it match the approved direction? The implementation decisions and their ramifications, what was subtracted, whether the goal was actually proved Correctness, second paths (BP-035), auth/routing from caller-controllable input (BP-031), legacy-shape tolerance (BP-030), concurrency and null boundaries Re-litigating a Decision the spec already settled and a human approved; style the codebase has already settled
Engineering calls — decided along the way, no product sign-off needed
  • Fixed both listing paths, not only the mixed-app one.
    • The deployed kitchen-sink installs an app-wide resolver (resolveKitchenSinkPrincipal), so it takes the host-principal path, not anonymousFlowIds.
    • Fixing only the anonymous path would have made the kitchen-sink test (default host) green while the real app stayed broken. The KS test now covers both configurations.
    • The cost is the behaviour change described above.
  • One helper for the catalog and the listings (routes/instance-caller.ts).
  • Kept the guard's anonymousFlowIds and the 401 on host-resolver refusal as they are.
    • The listings stop using anonymousFlowIds to decide rows of flows that authenticate themselves.
    • check_interrupted_requests (a mutating sweep addressed by user) still uses it unchanged; that route is out of scope.
  • Resolution is lazy in the mixed-app path and eager only when a host principal exists.
    • The anonymous path resolves a seat only when one of its rows is on the page, so management-routes-reachable never calls weekly-digest's resolver.
    • With a host principal, each self-authenticating resolver is asked once per request (cached) to decide whether the store query must widen.
  • Per-instance cache key is resolver identity plus requireUser/defaultUserId, as the catalog already had.
    • A resolver shared by several instances that answers differently per address (envelope.flowKind) is resolved at the first instance's address.
    • The catalog made the same documented trade-off.
  • Tenant is checked on every listed row, ahead of both verdicts (67e8085, Codex P1).
    • The active-request listing reads every tenant's entries (listAll) and never received the request's tenant. So a caller on one tenant's header saw another tenant's request and session ids whenever the owner check passed.
    • That was already true on main for open flows and the host principal. This PR's own-resolver verdict extended it to seat rows.
    • The handler now gets the tenant and requires tenantMatches(entry.tenantId, ctx.tenantId) first. list_sessions was already tenant-scoped by its store query, including the unscoped one. It now repeats the same per-row check as a second layer.
    • Not changed: check_interrupted_requests (the user-addressed sweep) also has no tenant check. It is out of scope and flagged to the coordinator.
  • Docs. docs-editor's REVISE is folded in (4383e0c). Each wording was checked against the code, and two were adjusted to stay true.
Everything else — verification, red→green, file list

Red on main → green. packages/engine/test/listing-instance-resolver.test.ts, with FSDEV_DEFAULT_MODEL/FSDEV_INTENT_* unset.

  • On main, the 4 positives fail:
    • a seat credential sees that seat's session and in-flight request, in a mixed app and with a host resolver;
    • tok-billing sees the billing seat's rows.
  • On main, the 4 negatives already pass: another org's credential, no credential (open-flow rows still listed, 200), a planted pin-refused row, and host-only callers.
  • With the fix, 8/8 pass.

Tenant (67e8085). Four cases in "the listings stay inside the caller's tenant": two tenants, with the same instance, user and org in each, and the caller on tenant A's header.

  • At 4383e0c, the three active-request cases fail (seat, open flow, host principal). On origin/main, the open-flow and host-principal cases fail too, so that part of the leak is older than this PR.
  • At 4383e0c, the sessions case passes, which shows the store's tenant scoping held on every path. With 67e8085, all four pass.
  • Fence breaks:
    • Remove the active-request tenant check: only those three cases fail (47 others in the listing, recovery and route-auth files pass).
    • Remove only the store's tenant argument: the per-row check still holds.
    • Remove both: the sessions case fails.

Fence breaks (resolver):

  • Revert only the four engine source files to origin/main. Only the 4 new engine positives and the 2 new KS positives fail. Every negative still passes.
  • Share one resolution across instances. The cross-seat cases fail by over-listing (tok-billing sees s-support), and so do the catalog's two cross-seat cases.
  • Drop the pin check. Only the pin case fails.

Kitchen-sink (apps/kitchen-sink/test/hired-seat-auth.test.ts):

  • After a hire, and a session opened with the admin token, GET /api/flows/sessions with that token includes the session.
  • That holds on the default host and on the resolveKitchenSinkPrincipal host that fsdev.config.ts installs.
  • A request with no credential and a request with the refused other-org token don't see it; both get 200.

Suites (at 67e8085, with #2191 merged in):

  • Kitchen-sink: 22/22 files, 161 tests.
  • Engine: 213 files, 2711 tests.
  • Engine typecheck and kitchen-sink tsc --noEmit are clean.
  • docs build is clean (at 4383e0c; 67e8085 touches no docs).

Files:

  • packages/engine/src/routes/instance-caller.ts (new): the per-instance caller resolver, flowAuthenticates, ownResolverVerdict.
  • packages/engine/src/routes/session-routes.ts, recovery-routes.ts: both listings check the tenant, then apply the own-resolver verdict; list_sessions widens the query only when needed.
  • packages/engine/src/routes/http-handlers.ts: builds the resolver once per request, and the catalog uses it; passes the tenant to the active-request listing.
  • packages/engine/src/routes/route-auth.ts: imports flowAuthenticates; comment.
  • docs/architecture/authentication.md, packages/engine/README.md, apps/docs/docs/server/authentication.md: the listing behaviour, including the 401 on host refusal.
  • .changeset/listing-instance-resolver.md: engine patch.
  • The tests described above.

Left alone: apps/kitchen-sink/lib/workforce-registrar.ts, the roster logic in flow-registry.ts (FIX-1549), and check_interrupted_requests (including its missing tenant check).

🤖 Generated with Claude Code

https://claude.ai/code/session_018e4MkWPYX62KRow9TSn75D

…-sink org (FIX-1563)

The test landed with `acme:tok-acme` as its admin credential. The app now
refuses any token that does not name `kitchen-sink`, so the admin flow
ran without its resolver and both admin-seat cases failed on main.

The test now boots the app's real `fsdev.config.ts`, as named-org.test.ts
does: the real host resolver, registrar and admin flow, with the token
bound to `kitchen-sink`. The in-app hire goes through mara's own `hire`
tool rather than a hand-built registration.

Both config-booting files get a 30s test timeout. A cold import of the
app takes about 4.8s alone, and two of them in parallel workers outran
vitest's 5s default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB
…chen-sink tokens (FIX-1563)

#2184 (FIX-1552) merged catalog cases written against the pre-#2159 acme/bravo
constants, which #2159 removed, so main fails kitchen-sink typecheck. The
operator's leg now lists with the kitchen-sink admin token; the other-org leg
uses the token whose entry was refused at boot.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB
…solver accepts (FIX-1566)

The session listing and the active-request listing judged every row by the
host-level resolver: in a mixed app they withheld every row of an instance
with its own resolver, and with a host resolver they compared rows against
the host's principal. An operator who could open a hired seat's session and
run its actions never saw that seat's sessions or in-flight requests listed.

A row owned by an instance with its own resolver is now judged through that
resolver at the instance's address (the host's own resolvePrincipal, so
resolver precedence, requireUser and defaultUserId apply as at the doors):
shown only when it accepts the caller, the row's userId and orgId are the
principal it returns, and a pinned instance's pin admits it. Resolution is
per instance and cached per request by resolver plus requireUser and
defaultUserId, the rule the catalog already used; the catalog and both
listings now share one helper (routes/instance-caller.ts).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018e4MkWPYX62KRow9TSn75D
…sted (FIX-1566)

Extends hired-seat-auth over HTTP: after a hire and a session opened with the
admin token, GET /api/flows/sessions with that token lists it, both on the
default host resolver and on the one fsdev.config.ts installs; no credential
and a refused token do not. Also repairs the undefined ACME/BRAVO catalog
arguments left by a merge between #2169 and #2184 (same edit as #2191), and
updates the server authentication user doc for the listing behaviour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018e4MkWPYX62KRow9TSn75D
@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 9:27pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 24, 2026 9:27pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 24, 2026 9:27pm UTC

Request Review

@linear-code

linear-code Bot commented Sep 24, 2026

Copy link
Copy Markdown

FIX-1566

@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_5592f672-50b1-4f0d-ac83-09bc8e50baaf)

…n base

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

Copy link
Copy Markdown
Collaborator Author

from: epic-lifecycle
session: epic/FIX-1528
kind: reply

Main's kitchen-sink tests are red, and this PR didn't cause it. At 777fe4d, hired-seat-visitor-auth.test.ts fails 2 tests. It came in with #2169 and uses an acme: admin token, which #2159 now refuses.

#2191 fixes it by changing the test only. I merged its branch into this one as 65d0bdd so CI here runs against a green base. The merge adds nothing once #2191 lands on main. This branch already made the same ACME/BRAVO edit to hired-seat-auth.test.ts as #2191, and git merged the two without conflict.

Locally with the merge: kitchen-sink passes 22/22 files (161 tests), and the three engine test files for the catalog, the listing resolver and management-routes-reachable pass (15 tests).


Generated by Claude Code

Applies the seven docs-editor findings to the server authentication page,
the engine README and the architecture doc, checked against the code:
owner-based wording for self-resolving flows, no-error-just-no-rows for a
rejected caller, the 401 when a configured host resolver rejects, the
shared-resolver cache condition (resolver plus requireUser/defaultUserId,
also corrected in the catalog row), and the userId filter in an unscoped
session query.

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

@jhoffner jhoffner left a comment

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.

Architect coherence: wait (draft) — direction looks sound once ready.

Listings judging each row through the owning instance’s resolver (plus owner/org/pin) matches the open/run doors and the HiredSeatOwnerPin lock. Centralizing with the catalog resolver is the right invent-kill.

When undrafted: call out the host-resolver behavior change (seat-refused rows no longer listed to the host principal). Land #2191 before or under this for kitchen-sink green.

Not owner approval / not the merge gate.

— FSD Architect

@jhoffner
jhoffner marked this pull request as ready for review September 24, 2026 21:15
@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-24T21:21:29.437965Z 4383e0c 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.

@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: 4383e0c061

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

…1566)

The active-request listing reads every in-flight entry across all tenants
(listAll) and never received the request's tenant, so a caller on one
tenant's header was shown another tenant's request and session ids whenever
the owner check passed. This was already true on main for open flows and for
the host principal; the own-resolver verdict extended it to seat rows.

Thread the request tenant into the active-request handler and require
tenantMatches(entry.tenantId, ctx.tenantId) before either verdict. The
session listing's store query was already tenant-scoped on every path,
including the unscoped one; it now repeats the same per-row check so
neither verdict can admit another tenant's row if that ever changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018e4MkWPYX62KRow9TSn75D
@jhoffner
jhoffner merged commit 2eac3b8 into main Sep 24, 2026
12 checks passed
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