[birme]

Summary

• Documents the current single-shot remote-mute path (muteParticipant: 'mute' -> isRemoteMute -> isRemotelyMuted -> muteInput) and the gaps it leaves.
• Defines two independent, persisted booleans on CallState: adminMuted and selfMuted, layered so neither overwrites the other.
• Specifies effective-mute logic effectiveMuted = adminMuted || selfMuted with track.enabled = !(adminMuted || selfMuted).
• Specifies the data-channel payload contract: existing muteParticipant: 'mute' plus a new mirror muteParticipant: 'unmute' (admin layer only), and keeps self-mute/unmute as local actions.
• Includes a worked table covering both acceptance scenarios (admin-unmute leaves a self-muted user muted; admin-unmute restores an admin-only-muted user to audible).

Test plan

• N/A — documentation only; no runtime code changed
• Design reviewed against acceptance criteria in Define admin-mute vs self-mute state model and unmute semantics #677
• Admin panel: global mute/unmute button per participant (UI + data-channel directive) #676 (admin mute/unmute UI) and Propagate global mute state to all participants (state sync + enforcement model) #678 (state propagation) will implement against this contract

Closes #677

🤖 Generated with Claude Code

[birme]

code-reviewer verdict: NEEDS CHANGES (self-authored PR — recorded as a marker comment since GitHub blocks state-bearing self-review).

An independent code-reviewer invocation (separate from the implementer) verified every cited identifier against the current source; the description of current behaviour is accurate and the proposed model meets #677's acceptance criteria. Changes required before this becomes the build-against spec:

Major

• §2 / §2.1 (effective-mute formula) drops the isProgramOutputLine dimension that §1.2 itself cites. Today admin mute is gated on !isProgramOutputLine and use-mute-input.tsx force-mutes isProgramOutputLine && !isProgramUser. Presenting track.enabled = !(adminMuted || selfMuted) as the complete rule would make Propagate global mute state to all participants (state sync + enforcement model) #678 (a) newly honour adminMuted on program-output lines and (b) possibly drop the forced-mute for non-program users. Retain the program-output special case in the formula or explicitly scope it out.

Minor

• §2 (line 88) maps isRemotelyMuted → adminMuted, but §5 bullet 1 (line 205) lumps isRemotelyMuted under selfMuted. §2 is correct; fix §5.
• The doc says adminMuted "replaces the single-shot role" but never tells Propagate global mute state to all participants (state sync + enforcement model) #678 to drop the consume/reset dispatch in use-mute-input.tsx:33-43. If adminMuted is persisted, that reset-after-consume must be removed or admin-only mute can never hold. Add a sentence.

Nit

• §3.2: state that from on the new "unmute" directive is injected by the SMB bridge (mirrors the mute path).

Moving the board item back to Ready for a follow-up commit addressing these.

[birme]

code-reviewer verdict: LGTM (self-authored PR — recorded as a marker comment since GitHub blocks state-bearing self-review).

An independent code-reviewer invocation (separate from the implementer) verified every cited identifier in docs/mute-state-model.md against the current branch source, confirmed all worked-example arithmetic, confirmed the four prior review points were addressed, and confirmed both #677 acceptance scenarios hold. No blocking or warning items; one optional editorial suggestion (present-tense "stored on CallState" under the Target-state heading). Proceeding to admin-merge.

[birme]

code-reviewer verdict: LGTM (carried forward to commit b534cb8).

The independent code-reviewer LGTM above was on the content at e14d48b. Commit b534cb8 is a prettier-only reformat (markdown table alignment + inline-code wrapping) with no semantic change, applied to fix the failing prettier CI check. Verdict unchanged; proceeding to admin-merge once CI is green.