Stream subsystem — the tail #1134's PR train did not close

[teetangh]

The #1134 train shipped as eight PRs (#1136–#1143). This is everything that audit surfaced and did not close, in one place, so the tail does not get lost when the train merges.

Each item is marked with how it was established: [live] read from the running Stream app, [code] verified against dev, [audit] carried from #1134 and not re-checked.

---

1. Never written — the two PRs that were planned and skipped

PR 9 · P3 cleanup

• [live] SDK upgrades. Installed versions run ahead of what package.json implies: @stream-io/video-react-sdk 1.35.2 (latest 1.40.2), stream-chat 9.41.1 (9.50.3), stream-chat-react 13.14.4 (14.11.x — a MAJOR, needs its own PR), @stream-io/node-sdk 0.7.54 (0.7.63).
• [code] Dead schema. MeetingSession.passcode and MeetingSession.hostKeys are written by the seeds and read by nothing. Class.recordingUrls bypasses the Recording model entirely.
• [code] MeetingAttendance is never seeded, so every surface that reads it renders empty locally.

PR 10 · Docs

• docs/stream/README.md does not exist but is linked from three files.
• Zero occurrences of "BetterAuth" across docs/stream/, while five files still describe NextAuth.
• 05-video-implementation.md documents a streamCallId format that has not been used for months.
• 13-recording-webhooks.md declares a StorageType enum that does not exist.
• Three different names for the org tag across three documents.

---

2. Open findings

2a. call_member can end a call for everyone — new, found during #1136 review triage

[live] The default call type grants call_member the end-call permission, and POST /api/meetings/[meetingId]/join assigns call_member to every participant. Any attendee can end a consultation for both sides from devtools.

ensure-call-type-grants.ts deliberately does not revoke it: EndCallButton.tsx:46 calls call.endCall() client-side, and the Stream role no longer separates host from participant (host-ness comes from custom.consultantUserId). Revoking it today would take the host's End Call button down with it.

Closing it needs one of:

• a server-side End Call route that re-checks host-ness via resolveMeetingAccess, then revoke the grant; or
• assigning admin (a real role on this type, 40 permissions) to access.role === "host" and call_member to everyone else, then revoke.

The same PR did revoke start-recording/stop-recording from call_member, because recording is server-only here — there is no client-side call.startRecording() in the tree — and leaving it granted made the pre-join consent gate from #1139 bypassable.

2b. No unban path calls restoreStreamAccess — new, found during #1136 review triage

[code] restoreStreamAccess() exists and has zero callers. A USER_BANNED action calls deactivateUser, which is permanent; if an operator lifts a permanent ban, the account is left unable to chat with no visible cause and nothing in the codebase undoes it.

#1136 narrowed the function's catch so a timeout or 5xx no longer resolves as a successful restore, but building the reversal path itself is a feature, not a review fix. Note that Stream documents neither outcome for reactivateUser on an already-active user, so the narrow match is asserted rather than documented — worth confirming against the live app when this is built.

2c. sendCallEvent has no subscriber

[audit] There is no call.on("custom") handler, so the notified count measures API acceptances rather than humans warned. Item 4 of #1134's "found wrong and not yet fixed" list, and the only one of those four still open.

2d. The remove-member control has never rendered for anyone

[code] lib/user.ts:82 mapRoleToStream collapses every non-staff account to Stream's "user" role — correct, it is the #981 least-privilege fix. But components/chat/ChannelInfoAndManageDialog.tsx:93 gates ownership on client?.user?.role === "CONSULTANT", an app role client.user.role can never hold. isEventOwner is permanently false and the button at :610 is dead.

Product decision needed — who may remove a member from a webinar/class channel? Plan owner only / owner + accepted collaborators (matching resolveMeetingAccess) / staff+admin only. Whichever it is, the check must read the session, never client.user.role.

Generalises: any comparison of client.user.role against an app role (CONSULTANT/CONSULTEE/STAFF) is dead code by construction. Worth grepping for. The identical bug in ChatSidebar is already fixed in #1142.

---

3. Missed by the audit — the highest-value unbuilt item

Session Timers (settings.limits.max_duration_seconds)

[live] Currently null on the default call type.

Setting it makes the SFU end the call server-side at the slot boundary, so Stream stamps ended_at whether or not our webhook pipeline works. Given the audit found 1,417 orphaned sessions and a webhook pipeline that had never processed a single event, this is the one control that would have degraded gracefully through the entire outage. Stream's own worked example for it is a telemedicine app with extendable one-hour appointments.

lib/meeting.ts explicitly declines to send it, deferring to #1070. That deferral is worth revisiting. Overlaps #472 (session overrun detection), which describes the same problem from the application side.

---

4. Deferred by #1143, stated in its body

• No background-blur toggle in the lobby.
• Background images are wired but not exposed — needs a curated asset set.
• No setSuppressionLevel slider for noise cancellation.

[live] Correction worth carrying: #1134's comment thread states the call type "already advertises noise_cancellation.mode: auto-on". It does not — settings.noise_cancellation reads back undefined on the live default type. This changes the billing risk framing for shipping @stream-io/audio-filters-web: the exposure is real but it is not already switched on. Confirm live before acting either way.

---

Not in here

• Priority DMs + Digital Products — paid async Q&A with an auto-enforced SLA, and paid downloads #1135 — priority DMs + digital products. Independent, not started.
• Adopt Stream's documented scheduled-call model: starts_at, members/roles, and backstage-enforced join windows #1070 / [RESILIENCE] Session overrun detection and conflict prevention #472 — cross-referenced above rather than duplicated.
• perf: bundle analysis results — Stream.io SDK at 771KB, 5 quick wins, phased optimization plan #639, feat: Hard-delete soft-deleted Stream users after 30-day grace period #535, [Feature] Recording Monetization: Access Tiers, Replay Store & Recovery Upsell #366, [Feature] Enterprise Recording Library - B2B Marketplace Expansion #367 — untouched by this train.

Part of #1134

[teetangh]

Stream role mapping — the mapping is right, its consumers are dead code

Expanding §2d with the full consumer inventory, plus one correction to something I asserted in the handoff that turned out to be wrong.

The mapping itself is correct and should not be touched

lib/user.ts:82 collapses five application roles into two Stream roles. ADMIN and STAFF become "admin", and everything else — CONSULTANT, CONSULTEE and ORG_WORKSPACE — falls through to "user".

That collapse is deliberate and it is right. It is the least-privilege change from #899 and #981, and the reasoning is recorded in the docblock immediately above the function. Stream's application-level admin role is a cross-application moderation power, so granting it to consultants would have given every consultant moderation authority over unrelated peer direct-message channels they have nothing to do with. Host privilege is instead granted channel-scoped, as a channel_moderator grant issued at channel creation time in actions/stream/chat/channel.action.ts:48 and actions/stream/chat/event-channel.action.ts:200 and :904. That is the pattern Stream's own permissions documentation recommends, and it is also what docs/stream/07-user-management.md and docs/stream/troubleshooting.md already describe. No change is warranted here.

Every client-side consumer of the result is dead code

The defect is entirely downstream. The mapping is lossy and it lowercases, so any client-side comparison of client.user.role against an application role string is unsatisfiable by construction. Three such comparisons exist. The table below lists each one, the branch state it was verified against, and what the always-false result actually costs.

Location	Comparison	Why it can never be true	Consequence
components/chat/ChannelInfoAndManageDialog.tsx:93 on dev, :96 on origin/fix/stream-chat-ux	client?.user?.role === "CONSULTANT"	Consultants map to "user"	isEventOwner is permanently false, so the remove-member button (:610 on dev, :637 on the #1142 branch) has never rendered for anybody
components/chat/ChannelInfoAndManageDialog.tsx:240-245 on dev, :243-248 on origin/fix/stream-chat-ux	userRole === "CONSULTANT" || userRole === "ADMIN" || userRole === "STAFF"	Consultants map to "user", and ADMIN/STAFF map to lowercase "admin", so all three disjuncts fail	isPrivileged is permanently false, so canTruncateChannel reduces to isCreator alone and nobody gains clear-chat rights from their role
components/chat/ChatSidebar.tsx:830 on dev	userRole === "consultant"	Only "user" and "admin" are ever produced, and neither is "consultant"	Empty-state copy only, and this one is already fixed — see below

Worth noting that the second of these is written correctly as three separate comparisons, so it is not the classic x === "A" || "B" truthiness mistake. Every comparison is well-formed. They are simply all unsatisfiable, which makes the bug harder to spot in review than the sloppier version would have been.

Correction: ChatSidebar really is fixed in #1142, and I was wrong to doubt it

The handoff I wrote claimed that the "already fixed in #1142" statement in §2d and in #1134's comment thread was wrong, on the basis that ChatSidebar.tsx at origin/fix/stream-video-quality still reads client?.user?.role at line 151 with no session-derived role anywhere in the file. That observation about the file is accurate, but the conclusion drawn from it is not, and the original statement stands.

The mistake was the branch. fix/stream-video-quality is #1143, and #1143 is a sibling of #1142, not a descendant of it — both branch from #1140, exactly as the merge plan in #1134's comment thread says. git merge-base --is-ancestor origin/fix/stream-chat-ux origin/fix/stream-video-quality returns false, and gh pr view 1143 --json files does not list ChatSidebar.tsx at all. So the copy of ChatSidebar.tsx visible on the #1143 branch is just dev's unfixed copy, which is why it looked broken.

On origin/fix/stream-chat-ux, which is where #1142 actually lives, the fix is present and complete. Line 24 imports useSession from @/lib/auth-client. Lines 178-181 derive the application role from the session, with useServerSessionFacts() as the fallback, and set isConsultant from it. The empty-state branch at line 781 now tests isConsultant rather than the Stream role, and the old userRole binding is gone entirely. The code even carries a comment at 175-177 explaining that mapRoleToStream collapses non-staff accounts to "user" so the old check could never be true — the same reasoning as this comment, written at the time.

Anyone re-verifying this should check origin/fix/stream-chat-ux and not origin/fix/stream-video-quality.

ChannelInfoAndManageDialog was not fixed alongside it

The dialog is in #1142's file list, so the branch owns it, but it did not receive the same treatment. On origin/fix/stream-chat-ux the ownership check at line 96 and the privilege check at 243-247 are still comparing client.user.role against application role strings, unchanged from dev. The sidebar was fixed only because a different change in that pull request forced the code path open, as the #1134 comment notes; the dialog was left alone.

This means the code fix has a natural home in #1142, but the blocker is unchanged and remains what §2d already says it is. The question of who may remove a member from a webinar or class channel is a product decision, not a UI commit, and the fix cannot be written until it is answered. Whatever the answer, the check has to read the session, exactly as ChatSidebar now does.

The test that looks like cover is not cover

__tests__/stream/types.test.ts:167-187 appears to pin the role mapping and does not. Inside the "Role mapping" block it declares its own local mapRoleToStream with a hardcoded Record<string, string> and then asserts against that local, never importing the real function from lib/user.ts. The production mapping could be inverted tomorrow and this test would still pass.

Its local map is also wrong in a second way, since it types the parameter as "ADMIN" | "CONSULTANT" | "CONSULTEE" | "STAFF" and omits ORG_WORKSPACE entirely. The real UserRole enum in prisma/schema.prisma:5141-5147 has five members.

This is the third decoy of the same shape in that one file. The file's own comment at lines 124-128 already flags two of them, generateEventChannelId and getChannelType, and explains that they were left alone because neither has an exported equivalent to call. That justification does not extend to this one: mapRoleToStream is exported from lib/user.ts, so the test can simply import it and assert against the real thing. The file is identical on dev and on every branch in the #1136-#1143 train, so this is unowned.

ORG_WORKSPACE is undocumented and untested

ORG_WORKSPACE reaches the default arm of the switch and becomes "user". That is almost certainly the intended outcome, since an org workspace operator manages organizations and neither books nor consults, so there is no reason to hand it Stream's global admin. The problem is that nothing says so. The docblock enumerates only staff and admins against everyone else, the enum member postdates the comment, and no test covers it. A one-line comment and a real assertion would close it.

[teetangh]

Two documentation facts that are wrong in-repo

Neither of these is a code bug and neither changes any design that has already shipped. Both are prose that a future reader would reasonably act on and be misled by, and neither is owned by anything currently open.

1. The webhook retry count is over-specified, and Stream's own documentation contradicts itself

The repository asserts a specific attempt count in two places. .claude/skills/stream-sdk/SKILL.md:48 says that "Stream retries 5× within a 15-second total budget (6s per attempt) and then drops the event forever". The webhook route says the same thing twice more, in the header docblock at app/api/stream/webhooks/route.ts:4-5 and again in an inline comment at :109-110, both phrased as "at most five times inside a FIFTEEN SECOND total budget (six seconds per attempt)".

One qualification on where that lives. Those two occurrences in the route are not on dev — they arrived with #1137 and are currently visible only on fix/stream-durability and the branches stacked above it. dev's copy of the route makes no claim about attempt counts at all. The SKILL.md line, by contrast, is on dev today and survives unchanged at the top of every open branch in the train, including #1140, #1141, #1142 and #1143, all of which touch that file without altering line 48.

The reason to stop asserting a number is that Stream publishes two different numbers and does not reconcile them. The webhooks overview breaks the limit down by failure mode and gives three attempts for a 408, 429 or >=500 response, two attempts for a network error, and three attempts for a request timeout. Their retries announcement instead says that events "will now retry for up to 15 seconds - or a maximum of five attempts, whichever comes first". Five is the ceiling in one document and is unreachable in the other. Picking either one and writing it down as fact means the repository is wrong against one of the two vendor sources no matter which is chosen.

What both sources agree on, in identical wording, is the timing envelope: the timeout of a single request is six seconds, and the request together with all its retries cannot exceed fifteen seconds in total. That is the unambiguous constraint, and it is also the load-bearing one. The ack-first design in #1137 rests on fitting signature verification and enqueue inside the budget and moving everything else into after(), and that argument is a function of the fifteen-second wall and the six-second per-request timeout alone. The attempt count never enters into it.

The recommendation is therefore to drop the count from all three sites and state the envelope instead — something to the effect that Stream allows six seconds per request inside a fifteen-second total budget across all retries, and then drops the event permanently. The design is unaffected; only the prose is over-specific, and only the prose needs to change.

Sources: Webhooks Overview — Stream Chat docs and Feature Announcement: Webhook Retries.

2. The skill file still prescribes a video-token pattern this codebase deliberately removed

.claude/skills/stream-sdk/SKILL.md:43-46 instructs the reader to "Scope video tokens to the call" using generateCallToken({ user_id, call_cids, validity_in_seconds }) and never a bare generateUserToken. That guidance is now wrong for this repository, and following it would send someone down a path the codebase has already explored and rejected.

lib/stream-client.ts records the decision directly, in a comment at lines 117-122 that #1136 introduced. The wrapper carrying a call_cids claim was in fact written for the join gate and then removed unused. The reason is structural rather than incidental: the video client here is an app-wide singleton holding one user token, and the JavaScript SDK has no per-call token on a shared client, so adopting a call-scoped token would require constructing a second client for every meeting. Membership is granted server-side by POST /api/meetings/[meetingId]/join instead, and generateVideoToken at lib/stream-client.ts:129-143 mints a plain user token with an explicit iat.

The rest of the tree is consistent with that and only the skill file is not. A repository-wide search for generateCallToken or call_cids outside Markdown returns three hits and all three are comments explaining the absence: lib/stream-client.ts:117, app/api/meetings/[meetingId]/join/route.ts:35, and scripts/stream/ensure-call-type-grants.ts:15. There is no call site. The only place in the repository that still tells a reader to use the pattern is SKILL.md:43, and it is unchanged on every open branch in the train.

The surrounding sentence at :45-46 should survive the edit, because it is still true and still important. Pairing the token with a call type whose user role lacks join-call while call_member holds it remains the access-control model here, and the warning that application-side checks are not access control because Stream's server API deliberately bypasses its own permission system is exactly right. What needs rewriting is the mechanism sentence: membership is granted server-side at join rather than encoded in a call-scoped token.

The comment in lib/stream-client.ts also names the condition under which the guidance would become correct again, which is worth carrying into the rewrite rather than deleting. Call-scoped tokens should come back when guest or magic-link join lands, since that flow genuinely needs them.

[teetangh]

Correction: session timers do not work the way this issue assumes

This issue records session timers as the highest-value unbuilt item on the grounds that the SFU would end calls at the slot boundary. It would not, and the difference is the difference between a safe feature and an incident.

max_duration_seconds has no relationship to starts_at and does not run to a wall-clock deadline. It counts from the moment the session starts, which is when the first participant joins. Stream's guides state this on every platform (Flutter, JavaScript).

Our join windows admit a consultant 15 minutes early and a consultee 10 minutes early (CONSULTANT_JOIN_WINDOW_MS, CONSULTEE_JOIN_WINDOW_MS). So if we set the cap to the booked slot length, a consultant joining early to check their camera starts the clock early, and Stream hard-terminates the session up to fifteen minutes before the booked end of something the consultee paid for. Both parties are ejected mid-sentence with no recourse.

That is precisely the failure lib/meeting.ts cites when it declines to send the field. On this specific point the existing code comment is correct rather than over-cautious, and it should not be "fixed".

It is still worth building — reframed

Set generously: booked duration, plus the early-join window, plus a grace period. A 60-minute slot gets something like 90 to 120 minutes. As a backstop rather than as enforcement, it buys three things nothing else in the stack provides.

Stream stamps ended_at regardless of our webhook pipeline. This is the argument that survives the correction, and it is the strongest one. #1134 found 1,417 sessions with no endedAt behind a webhook pipeline that had never processed a single event. A server-side duration cap is the only control that degrades gracefully through that kind of outage, because it does not run on our infrastructure. #1155 fixed the setDisconnectionTimeout default that caused those orphans — but that fix lives in our client, and this does not.

It bounds the worst-case bill. A call nobody leaves — a forgotten tab, a phone in a pocket, a client that fails to tear down media — meters participant minutes indefinitely at $1.50 per 1,000. Today the only thing between us and an unbounded meter is session.inactivity_timeout_seconds: 30, which requires everyone to actually disconnect.

It gives #472 its server-side half. Stream emits no event before cutoff, but call.state.session.timer_ends_at is a clean single source of truth for the client clock, which readClock currently derives independently.

Two things that make it easier than this issue assumed

It is settable per call, not only on the call type, via settings_override on the existing getOrCreate in lib/meeting.ts — so it can be computed from the anchor slot rather than fixed globally. And own_capabilities on the live call type includes change-max-duration, confirmed in a live read, so it can be extended during a call with call.update(), which emits call.updated to participants.

It is free. It appears as a line item nowhere on the pricing page or in the pricing guide.

Effort is roughly one to two days.

Answer these three before it ships

None is documented, and the first one is the whole case for the feature:

1. Does expiry emit call.ended or call.session_ended on the webhook? The docs say the call is "marked as ended" but name no event — and that event is exactly what we would be depending on.
2. Does the timer reset if all participants leave and a new session starts within the same call? Directly relevant to network drops.
3. What is the maximum accepted value?

All three are answerable in a single test call against the dev app.

Full assessment, with the rate card and the rest of Stream's paid surface, is in #1160.