rbrooks/Quest-Board

Watch

Fork

You've already forked Quest-Board

Code Issues 58 Pull requests 7 Projects Releases 76 Packages Wiki Activity Actions

[Backend] Disambiguate speaker labels — nicknames, collisions, and the snowflake fallback #344

New issue

Closed

opened 2026-08-25 20:39:01 +00:00 by claude-bot · 1 comment

claude-bot commented

2026-08-25 20:39:01 +00:00

Collaborator

Copy link

Severity: MEDIUM. Found in the August 2026 session lifecycle review (#319).

The defect

Three ways a speaker label goes wrong before the LLM ever sees the transcript:

Guild nicknames are ignored. recording.py:717-723 resolves names via bot.get_user(...).display_name, which is global_name or name — the guild nickname is never consulted. Players whose server nick is their character name lose that identity. Worse, the live recording dashboard does prefer the guild member (services/recording_status.py:28), so the name the GM sees during the session differs from the one in the transcript.
Identical display names collapse. Two guild members can legally share a display name. Both tracks carry the same label, and character_map is keyed by display name (reminder_tasks.py:2077-2113), so both map to whichever entry won a last-write-wins dict insert. Two players merge into one speaker.
Cache miss falls back to a raw snowflake. If the user is not in the bot's cache, the speaker is labelled with a bare Discord id, and the transcript contains lines like [00:12:01] 184623...: text which the LLM will merge into, or guess as, a named player. reminder_tasks.py:2059 does the same for a WAV missing from speakers.json.

Proposed fix

Resolve names from the guild member first, falling back to the global user. Key the character map by Discord user id, not by display name — the id is already in the filename. On a display-name collision, disambiguate in the rendered label. Never emit a bare snowflake: fall back to a stable readable form and flag the session so the GM can correct it.

Acceptance criteria

Speaker names prefer the guild nickname, matching the live dashboard
The character map is keyed by user id
Colliding display names are disambiguated in the transcript
A cache miss never produces a bare snowflake label, and flags the session
Tests cover nickname vs global name, two members sharing a name, and a cache miss

**Severity: MEDIUM.** Found in the August 2026 session lifecycle review (#319). ## The defect Three ways a speaker label goes wrong before the LLM ever sees the transcript: 1. **Guild nicknames are ignored.** `recording.py:717-723` resolves names via `bot.get_user(...).display_name`, which is `global_name or name` — the **guild nickname is never consulted**. Players whose server nick is their character name lose that identity. Worse, the live recording dashboard *does* prefer the guild member (`services/recording_status.py:28`), so the name the GM sees during the session differs from the one in the transcript. 2. **Identical display names collapse.** Two guild members can legally share a display name. Both tracks carry the same label, and `character_map` is keyed by display name (`reminder_tasks.py:2077-2113`), so both map to whichever entry won a last-write-wins dict insert. Two players merge into one speaker. 3. **Cache miss falls back to a raw snowflake.** If the user is not in the bot's cache, the speaker is labelled with a bare Discord id, and the transcript contains lines like `[00:12:01] 184623...: text` which the LLM will merge into, or guess as, a named player. `reminder_tasks.py:2059` does the same for a WAV missing from `speakers.json`. ## Proposed fix Resolve names from the **guild member** first, falling back to the global user. Key the character map by Discord user id, not by display name — the id is already in the filename. On a display-name collision, disambiguate in the rendered label. Never emit a bare snowflake: fall back to a stable readable form and flag the session so the GM can correct it. ## Acceptance criteria - [ ] Speaker names prefer the guild nickname, matching the live dashboard - [ ] The character map is keyed by user id - [ ] Colliding display names are disambiguated in the transcript - [ ] A cache miss never produces a bare snowflake label, and flags the session - [ ] Tests cover nickname vs global name, two members sharing a name, and a cache miss

claude-bot added this to the v4.0.0 - Session Pipeline Accuracy milestone

2026-08-25 20:39:01 +00:00

claude-bot added the

labels

2026-08-25 20:39:01 +00:00

rbrooks referenced this issue from a commit

2026-08-26 01:02:23 +00:00

feat(backend): resolve speaker attribution deterministically in code (#329, #342, #344)

rbrooks referenced this issue from a commit

2026-08-28 00:45:01 +00:00

fix(bot): never write a bare Discord snowflake as a speaker name (#344)

rbrooks referenced this issue from a commit

2026-08-28 17:01:54 +00:00

fix(backend): close two attribution gaps found by verifying #342 and #344

rbrooks referenced this issue from a commit

2026-08-28 18:57:44 +00:00

feat(backend): anchors, a rollback lever, and a name the bot could not find

claude-bot referenced this issue

2026-08-28 19:15:21 +00:00

[Backend] Resolve every speaker label to a character in code, and delete the prompt-time rename #329

claude-bot commented

2026-08-28 19:15:55 +00:00

Author

Collaborator

Copy link

Verified; the two remaining gaps fixed in dd8f305 and 7a689a9.

Criteria

Speaker names prefer the guild nickname, matching the live dashboard — met, and tested against the pre-fix behaviour.
The character map is keyed by user id — met by deletion: character_map and _apply_character_names no longer exist. resolve_speakers is keyed on owner_id throughout, and persistence carries the id.
Colliding display names are disambiguated in the transcript — _disambiguate qualifies with an id suffix and loops on a second-order collision.
A cache miss never produces a bare snowflake label, and flags the session — first half was fixed at the producer only; second half handled differently, below.
Tests cover nickname vs global name, two members sharing a name, and a cache miss — all three exist and fail under pre-fix code.

The snowflake guard was fixed at the producer only

2114f42 stopped the bot writing a bare id, and its own message notes that speakers.get(stem) or default catches only a missing key. The backend consumer kept exactly that or, so a snowflake present as the value is truthy and walked straight through into the transcript — where the LLM reads it as a person's name and merges it into a real player, which is this issue's original symptom.

That is a live path, not a leftover. Every speakers.json written before that commit has exactly that shape; CLAUDE.md states the per-session audio directory is never deleted automatically; and reprocess is one of four documented routes back into process_audio. An old recording reprocessed on a new backend reproduces the bug in full.

resolved_speaker_name now checks symmetrically against the stem and mirrors the bot's unknown_speaker_label, so a track handled by either side reads the same to a GM.

"Flags the session" — recovered instead

Looking at where the gap actually is, flagging turned out to be the weaker answer.

A linked member with a character was never affected — the character name wins over anything the bot wrote.
An unlinked speaker has nothing to recover, and already surfaces to the GM through session.attendance_unmatched_speakers — the attendance screen, which is exactly where someone goes to say who an unrecognised speaker was. That is the flag, and it already existed.
That leaves one combination: a linked member with no character set. Their placeholder became the transcript label while the database knew precisely who they were.

So the linked account's display name now fills in — but only when the bot produced a placeholder, because the bot reads Discord directly and prefers the guild nickname, which is normally what a table calls each other. Its answer wins whenever it has one.

Recovering the name is strictly better than flagging that it is missing, so the criterion is met in substance rather than in form. If you would still like an explicit session-level marker on top of this, that is a small follow-up and worth its own issue rather than being assumed.

One residual the sweep missed

recording_status.py still had getattr(member, "display_name", str(member_id)) for uncaptured_members — the last bare-snowflake fallback. Lower stakes than the transcript path (no LLM reads it as a person) but the same unreadable string in front of the same GM, and there was already a helper for it.

Closing.

**Verified; the two remaining gaps fixed in `dd8f305` and `7a689a9`.** ## Criteria - [x] **Speaker names prefer the guild nickname, matching the live dashboard** — met, and tested against the pre-fix behaviour. - [x] **The character map is keyed by user id** — met **by deletion**: `character_map` and `_apply_character_names` no longer exist. `resolve_speakers` is keyed on `owner_id` throughout, and persistence carries the id. - [x] **Colliding display names are disambiguated in the transcript** — `_disambiguate` qualifies with an id suffix and loops on a second-order collision. - [x] **A cache miss never produces a bare snowflake label, and flags the session** — first half was fixed at the *producer only*; second half handled differently, below. - [x] **Tests cover nickname vs global name, two members sharing a name, and a cache miss** — all three exist and fail under pre-fix code. ## The snowflake guard was fixed at the producer only `2114f42` stopped the bot **writing** a bare id, and its own message notes that `speakers.get(stem) or default` catches only a *missing* key. The backend consumer kept exactly that `or`, so a snowflake **present as the value** is truthy and walked straight through into the transcript — where the LLM reads it as a person's name and merges it into a real player, which is this issue's original symptom. That is a live path, not a leftover. Every `speakers.json` written before that commit has exactly that shape; CLAUDE.md states the per-session audio directory is never deleted automatically; and reprocess is one of four documented routes back into `process_audio`. **An old recording reprocessed on a new backend reproduces the bug in full.** `resolved_speaker_name` now checks symmetrically against the stem and mirrors the bot's `unknown_speaker_label`, so a track handled by either side reads the same to a GM. ## "Flags the session" — recovered instead Looking at where the gap actually is, flagging turned out to be the weaker answer. - A linked member **with** a character was never affected — the character name wins over anything the bot wrote. - An **unlinked** speaker has nothing to recover, and already surfaces to the GM through `session.attendance_unmatched_speakers` — the attendance screen, which is exactly where someone goes to say who an unrecognised speaker was. That *is* the flag, and it already existed. - That leaves one combination: **a linked member with no character set.** Their placeholder became the transcript label while the database knew precisely who they were. So the linked account's display name now fills in — but **only** when the bot produced a placeholder, because the bot reads Discord directly and prefers the guild nickname, which is normally what a table calls each other. Its answer wins whenever it has one. Recovering the name is strictly better than flagging that it is missing, so the criterion is met in substance rather than in form. If you would still like an explicit session-level marker on top of this, that is a small follow-up and worth its own issue rather than being assumed. ## One residual the sweep missed `recording_status.py` still had `getattr(member, "display_name", str(member_id))` for `uncaptured_members` — the last bare-snowflake fallback. Lower stakes than the transcript path (no LLM reads it as a person) but the same unreadable string in front of the same GM, and there was already a helper for it. Closing.

claude-bot closed this issue

2026-08-28 19:16:24 +00:00

rbrooks referenced this issue from a commit

2026-08-31 17:31:26 +00:00

fix(recording): finish a recording the bot died in the middle of (#399)

claude-bot referenced this issue

2026-08-31 17:33:05 +00:00

fix(recording): finish a recording the bot died in the middle of (#399) #470

claude-bot referenced this issue

2026-08-31 17:33:40 +00:00

[Bot] Stop the startup sweep from deleting recordings it told the user were saved #399

claude-bot referenced this issue

2026-08-31 17:54:23 +00:00

[Bot] Stop the startup sweep from deleting recordings it told the user were saved #399

rbrooks referenced this issue from a commit

2026-09-05 03:50:26 +00:00

feat(evals): assembler and seeding — clips to the bot's own directory contract (#433)

rbrooks referenced this issue from a commit

2026-09-05 03:50:26 +00:00

test(evals): the Whisper shim and the negative fixtures (#433)

claude-bot referenced this issue

2026-09-05 03:51:34 +00:00

feat(evals): synthetic-session harness — an invented 30-minute session that exercises transcription end to end (#433) #497

rbrooks referenced this issue from a commit

2026-09-05 05:20:24 +00:00

feat(evals): assembler and seeding — clips to the bot's own directory contract (#433)

rbrooks referenced this issue from a commit

2026-09-05 05:20:24 +00:00

test(evals): the Whisper shim and the negative fixtures (#433)

claude-bot referenced this issue

2026-09-05 16:03:36 +00:00

Synthetic-session harness: marker scorer denominator, vocabulary-gap severity, hotwords #506

No Branch/Tag specified

main

feat/1328-fill-it-in

feat/1328-fill-frontend

feat/1328-fill-backend

feat/9-foundry-push

fix/9-foundry-live

feat/9-foundry-push-frontend

renovate/celery-5.x

feat/5-foundry-connect

feat/9-foundry-push-backend

feat/9-foundry-push-module

feat/5-foundry-frontend

feat/5-foundry-backend

feat/5-foundry-module

release/v4.8.0-rc1

docs/d341-convert-draft

feat/958-update-to-version

feat/958-convert-sheet

feat/958-pathbuilder-import-frontend

fix/1360-heading-order

feat/958-pathbuilder-import-backend

feat/11-weekly-digest

feat/1341-auto-update

docs/d332-superseded

chore/1345-names-cleanup

feat/1342-mentioned-pages

feat/1328-recipes

fix/1346-pgdg-key

perf/1247-shared-recording-stream

chore/132-gitleaks-allowlist

release/v4.7.1

spike/foundry-module

release/v4.7.1-rc1

docs/decisions-d332-d337

fix/bot-certifi

chore/release-4.7.0

chore/release-4.7.0-rc4

chore/deps-4.7.0

chore/release-4.7.0-rc3

fix/1280-quote-must-say-it

fix/1257-names-row-squeeze

chore/release-4.7.0-rc2

fix/1245-pg-upgrade-count

chore/release-4.7.0-rc1

feat/1257-names-in-prep

feat/1257-be

feat/1257-fe

feat/1257-rating-fixes

design/1328-fill-it-in

feat/1257-name-splits

fix/1326-redis-503

feat/1280-fact-suggestions

feat/1280-be

feat/1280-fe

design/1280-fact-suggestions

feat/1279-infobox

feat/1279-be

feat/1279-fe

feat/1321-shelf-copies

design/1279-infobox

feat/1243-table-find

feat/1257-who-rated

feat/1243-prep-drawer

feat/1243-sheet-pickers

design/1243-browse-in-place

feat/1315-hotwords-default

feat/1242-system-filters

feat/1257-more-name-styles

feat/506-leg3-hotwords

design/1242-system-filters

fix/1302-packs-polish

feat/1241-rules-library

design/1241-rules-library

feat/1245-postgres-18

integ/4.6.2

fix/1263-map-ui-2

fix/1263-map-server

fix/1263-map-ui-1

fix/1261-editor-link-menu

fix/1229-axe-4.14-name-mismatch

renovate/axllent-mailpit-1.x

renovate/eslint-monorepo

renovate/authlib-1.x

chore/release-4.6.0

chore/release-4.6.0-rc2

fix/460-rc2-screens

fix/460-rc2-server

fix/release-prerelease-exit

chore/release-4.6.0-rc1

feat/125-campaign-templates

feat/126-calendar

feat/1181-pictures-and-files

feat/1190-event-people

integ/4.6.0

feat/1191-line-of-the-night

feat/1200-starter-packs

chore/bot-multidict-and-playwright-group

fix/1202-this-week-answered-count

fix/122-124-leftovers

fix/1178-get-routes-that-write

fix/1203-journeys-check-names

design/125-campaign-templates

feat/126-calendar-engine

design/126-in-world-calendar

fix/1189-cited-stamp-in-range

fix/1189-v4-looser-check

fix/1189-richer-beats

fix/1113-export-bind-lists

fix/1154-release-notes-by-file

chore/release-4.5.0

chore/release-4.5.0-rc12

fix/1135-wiki-markup-as-text

fix/demo-usage-cost-in-window

chore/release-4.5.0-rc11

fix/1121-sheet-consistency

fix/1121-sheet-5e-terms-and-card-hp

copy/1122-busiest-pages

fix/1121-relevant-choices

fix/1121-wiki-create-npc-save-sheet-links

fix/1029-menu-stays-on-screen

docs/prototype-transcript-bin-wording

fix/1023-editor-save-row-back-scroll

fix/1020-search-exact-first

fix/1020-table-prep

fix/1020-shell-wordmark-footer-bell

fix/1020-wiki-article-party

fix/872-admin-kept-until-phone-tables

feat/l13-milestone-level-waiting

fix/1000-1001-bell-older-setup-context

fix/999-pronouns-in-prompts

fix/l19-other-class-feats

fix/1010-transcript-window-ordinary-confirm

docs/d254-d269-decisions

fix/702-member-search

fix/680-transcript-bin

fix/993-unidentified-prompts

fix/841-redis-timeouts

fix/990-binned-not-exported

fix/830-export-prep-shelf

fix/deps-audit-2026-10-01

fix/877-title-reads

fix/798-audio-received-at

build/lane11-17-j7

build/lane11-16-levelup

build/lane11-14-seams

build/lane11-14-seed

build/lane11-15-start

build/lane11-13-old-block-out

fix/980-review-r3

build/lane11-12-block

build/lane11-8-packs

fix/demo-seed-canonical-names

build/lane11-11-hot-half

docs/l11-decisions

build/lane11-7-convert

build/lane11-10-editing

fix/npm-audit-brace-expansion

build/lane11-9-sheet-page

fix/bot-pyjwt

build/lane11-6-content

fix/lane11-rank-names

build/lane11-2b-language

build/lane11-4-js-evaluator

build/lane11-3-server

build/lane11-5a-pf2e

build/lane11-5b-5e

feat/design-admin

build/lane11-2-evaluator

build/lane11-1-sheet-pieces

build/lane11-0-drawing

fix/943-quest-objectives-fk

fix/prepsheet-shelf-flake

fix/945-leftovers

build/demo-gm-copy

fix/901-email-landings

build/lane10-8-journeys

build/demo-seed-lanes-8-10

fix/887-gm-own-confirmation

build/lane9-5-j1-admin

fix/918-audience-click

fix/useasync-overtaken

ci/939-critical-path

test/937-backend-suite-speed

chore/claude-orchestration

fix/924-xp-gm-only

fix/session-stale-poll

docs/decisions-d239-d242

fix/930-pypdf

build/lane8-journeys

build/925-quest-editor

fix/894-private-page-pictures

build/lane8-p4-drafts

build/lane8-p7-map

build/lane8-p6-handouts-rules

fix/wiki-fixture-names

build/lane10-d227-test-usage

fix/rsvp-horizon-test-tuesday

fix/media-volume-owner

build/lane8-p3-editor

fix/912-unidentified-rename

build/lane8-p5-party-quests

build/lane8-handout-takeback

build/lane10-pickers

build/lane8-p2-article

build/lane8-6-map

build/lane10-7b-email-pages

build/lane8-5-handouts

build/lane10-7a-test-the-bot-pages

build/lane8-p1-pages

build/lane8-4-quests

build/lane8-2b-feeds

build/lane8-3-parties

build/lane8-2a-links

build/lane10-5-commands

build/lane9-6-seed

build/lane10-4b-reactions

build/lane9-4d-pages

build/lane9-4c-pages

build/lane10-4a-posts

build/lane10-3-email

fix/891-web-fonts

build/lane9-4b-pages

build/lane10-6-test-the-bot

build/lane10-2-notify-out

build/lane8-1-wiki-text

build/lane9-4a-frame

design/lane10-drawings

fix/j6-budget

fix/j5-phone-flake

fix/869-test-leaks

fix/843-record-start-followups

build/lane7-all

build/lane6-all

build/lane9-b2-server

chore/changelog-fragments

docs/decisions-d218

build/lane9-a-owner-overview

fix/rule-card-level-label

fix/834-retention-semantics

fix/o3c-record-without-announcement

docs/decisions-d179

docs/decisions-d131-d170

fix/851-commit-before-response

build/lane6-j3-seed

build/lane9-b1-d67-identity

fix/841-blocking-loop

build/lane9-c-backups-audit

fix/vote-race-and-start-commit

fix/recording-announcement

fix/proposal-read-leak

fix/last-admin-guard

build/lane6-p4c-planning

build/lane6-p4b-margin

build/lane6-p4a-sheet

build/lane5-j4-seed

build/lane6-base

build/lane7-pages-talk

build/lane5-pages

build/lane7-pages-safety

build/lane7-p3-safety

build/lane7-p2-notify

build/lane6-p3-planning

build/lane6-p2-history

build/lane6-p1b-items

build/lane7-p1-threads

build/lane5-p6-faces

build/lane6-p1a-sheet

build/lane5-p5-find

build/lane5-p4a-board

build/lane5-p4b-scenes

build/lane5-p3-live

build/lane5-base

build/lane5-p2-cards

docs/lane5-decisions

build/review-r2-wide

fix/review-r1

build/lane5-p1-scenes

build/demo-seed

build/lane4-journeys-j5

build/lane4-page-review-b

build/lane4-page-review-a

build/lane4-page-read

build/lane4-journeys

build/lane4-page-sess2

build/lane4-page-sess1

build/lane4-notes

build/lane4-discord-on-approval

build/lane4-scheduling

build/lane4-versions

build/760-session-number

build/lane4-decisions

build/797-erase-no-regenerate

build/test-race-audit

build/lane3-completions

build/794-dark-only

build/796-titles-scroll

build/791-retention-anchor

build/a11y-sweep

build/shell-followups

build/retention-preview

build/753-backup-readback

docs/d91-d93

build/lane3-j1

build/ci-harness-paths-selftest

fix/useauth-test-race

build/ci-harness-paths

build/777-ai-settings-read

build/lane3-settings-c

build/lane3-settings-b

build/lane3-j6

build/lane3-sessionform

build/lane3-settings-a

build/lane3-members

build/lane3-thisweek

build/lane3-story

chore/87-align-python-3.12

v4.8.0-rc1

v4.7.1

v4.7.1-rc1

v4.7.0

v4.7.0-rc4

v4.7.0-rc3

v4.7.0-rc2

v4.7.0-rc1

v4.6.2

v4.6.2-rc4

v4.6.2-rc3

v4.6.2-rc2

v4.6.2-rc1

v4.6.1

v4.6.1-rc1

v4.6.0

v4.6.0-rc2

v4.6.0-rc1

v4.5.3

v4.5.3-rc1

v4.5.2

v4.5.2-rc1

v4.5.1

v4.5.1-rc2

v4.5.1-rc1

v4.5.0

v4.5.0-rc12

v4.5.0-rc11

v4.5.0-rc10

v4.5.0-rc9

v4.5.0-rc8

v4.5.0-rc7

v4.5.0-rc6

v4.5.0-rc5

v4.5.0-rc4

v4.5.0-rc3

v4.5.0-rc2

v4.5.0-rc1

v4.4.1

v4.4.0

v4.3.0

v4.2.3

v4.2.2

v4.2.1

v4.2.0

v4.1.2

v4.1.1

v4.1.0

v4.0.1

v4.0.0

v3.11.4

v3.11.3

v3.11.2

v3.11.1

v3.11.0

v3.10.0

v3.9.1

v3.9.0

v3.8.0

v3.7.0

v3.6.1

v3.6.0

v3.5.0

v3.4.1

v3.4.0

v3.3.0

v3.2.0

v3.1.0

v3.0.0

v2.1.0

v2.0.0

v1.1.0

v1.0.0

v0.12.0

v0.11.0

v0.10.0

v0.9.1

v0.3.3

v0.9.0

v0.8.0

v0.3.2

v0.3.1

v0.3.0

v0.7.0

v0.6.0

v0.5.0

v0.4.0

v0.2.1

v0.2.0

v0.1.1

v0.1.0

Labels

Clear labels

backend

Issue related to the backend

bot

Issue related to the bot

bug

Something is not working

duplicate

This issue or pull request already exists

enhancement

New feature

frontend

Issue related to the frontend

More information is needed

recording

Issue related to the recording system

security

Security hardening / vulnerability work

No labels

Milestone

Clear milestone

No items

No milestone

v4.0.0 - Session Pipeline Accuracy

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

rbrooks/Quest-Board#344

Reference in a new issue

Repository

rbrooks/Quest-Board

Title

Body

No description provided.

Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?

Rows
Columns