Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

120 KB
Raw Blame

Channels and Messaging

Deleting a channel

The channel owner can permanently delete their channel. A team owner or admin can also delete a team channel belonging to their own team. Being a participant, administering another team, or sharing a team with the channel creator does not grant permission to delete it.

Use Delete from the channel row or title menu, or the mobile long-press menu. Confirm the deletion in the existing delete dialog; it removes the channel for everyone. The same permission rule applies to the delete hotkey and bulk action. If a bulk deletion partly succeeds, confirmed deletions stay removed and only failed items remain in the dialog for retry.

User mentions sent by integrations may contain only userId. For human user IDs, messages and editors resolve the current name and fall back to the email local part when lookup fails. Verify that these mentions remain intact when editing and saving a message; integrations need not supply email or displayName.

Channel calls

A channel call may have its own row and thread in the channel. See calls whose discussion is a channel thread.

Channel list previews

Message text in channel rows and Home cards is display-only, including quoted thread previews. Clicking a link or mention in that text opens the surrounding channel or thread, and Tab skips embedded controls. Screen readers still announce the message text, including link labels and mention names, once per preview. Verify wide and narrow rows and channel/thread cards; links and mentions remain interactive inside the opened conversation.

Conversation headers and shared detail breadcrumbs use the same identity icon: the recipient for human DMs, the persona for agent DMs, and the channel picture or glyph for named channels. Message and thread breadcrumbs resolve identity from their parent channel rather than the message or thread ID.

Message links

A channel search namespace with threadId and no messageId targets the thread root. Home, Chat, and the full-screen touch conversation normalize this URL in the shared channel search schema; an explicit message continues to target its reply within that thread.

Bare URLs, common bare domains, and email addresses are clickable in opened messages, including agent/API messages and older messages. Explicit Markdown links still use their label. Inline code, code blocks, and escaped URLs stay literal. Removing a link in the composer remains effective after sending and reopening the message for editing.

Verify a bare App Store URL on desktop and mobile, a percent-encoded URL, a URL containing Markdown punctuation, and Remove link → send → reopen. Channel and Home previews remain display-only as described above. The backend-free browser check is in apps/web/src/lib/core/component/LexicalMarkdown/component/core/browser-test/README.md.

Block formatting

Selecting several paragraphs and choosing Quote or a heading in the floating format toolbar applies it to the same paragraphs in either selection direction. Verify a selection from the last paragraph back to the start of the first: the first paragraph must receive the format too. A range ending at the start of the following paragraph leaves that following paragraph unchanged. Typing > creates a quote. Pasting text with paragraph breaks into that quote keeps all pasted paragraphs quoted, including HTML and text copied from another Macro editor. Inline formatting survives. Verify an empty quote and a selection within a quote, then type after the paste and save the message; every pasted paragraph must still have the quote styling. Selections across adjacent quoted paragraphs preserve quoting too. A selection that includes unquoted paragraphs keeps the normal paste behavior. The backend-free quote check is documented in the Markdown browser-test README linked above.

Query document ownership

Switch between Home and Channels repeatedly, including after backgrounding the native app. Conversation queries must remain reusable: their operation names and serialized GraphQL documents must stay consistent. The backend-free desktop and iPhone WebKit regression is bunx playwright test --config src/lib/urql-solid/browser-test/playwright.config.ts from apps/web.

Data and loading state publish together, so automatic pagination observes the new page cursor before deciding whether to request another page.

Empty direct messages

An empty human DM shows the centered conversations illustration and “Say hello” above the composer. The copy explains that recipients without a Macro account receive the message by email. Opening the DM sends nothing.

Opening a person you have no DM with shows this same empty DM, with their name and avatar in the header, under a temporary pending-dm- id kept only in that tab. Nothing exists on the server, so the DM is in neither person's list until the first message creates it and the view becomes the real conversation. Check that leaving without sending creates nothing, that the other person's list gains the DM only after the send, and that reloading a pending-dm- URL opens the Chat list on desktop and closes the pane on touch.

Sending a human message queues an immediate email for nonusers, including follow-up messages, replies, and mentions; registered users retain their notification preferences. Check narrow and wide panes: the composer stays usable, and the empty state vanishes when the first timeline entry appears. Agent DMs keep their own UI.

Create a channel

Chat offers separate New channel and New direct message actions with either sidebar layout. New channel and the global Create menu use this three-step flow:

  1. Create → Channel G. Dialog Create a channel opens on step 1 of 3 with the Name textbox focused.
  2. Fill the name and click Next. Step 2 of 3 shows Visibility, with Team — anyone on your team selected by default. Team channels are always discoverable to teammates.
  3. For a team channel, click Create. For a private channel, select Private — only specific people and click Create. Creation navigates to the channel (as a split pane: .../channel/<uuid>); a system row Channel <name> created appears.
  4. Step 3 of 3 is an optional invite dialog for either channel type. The recipient combobox searches people and saved agents by name; it also accepts complete email addresses. Select a suggestion or press Enter to tokenize it. An unknown complete email appears as Invite with a paper airplane icon. Raw text left in the input is not submitted. Click Add when recipients are selected, or Skip for now to finish without invitees. Selected agents are added through the channel's agent membership endpoint. For team channels, Automatically add teammates defaults on; turning it off leaves the channel discoverable without automatically adding current or future teammates. The switch choice is applied when the invite dialog is finished or closed.

Team channels are always discoverable to the team. Private channels can only be viewed or joined by invitation. A DM is a private conversation between two people, or between one person and an agent persona. An external email can be selected as a channel participant. For an unregistered recipient, clicking Add sends an email invite.

The first message in a DM to an unregistered recipient sends an email saying <sender email> sent you a message on Macro, with the message and a View message button leading to signup. It must not invite the recipient to #<their own name>. Named-channel invites still show #<channel name> and Join channel. Verify both emails in local Mailpit using distinct, unregistered test addresses; repeat with a plus-addressed DM recipient to check the email-name fallback.

Private conversations with an agent

Agent DM discovery is on in development builds (dev.macro.com and bun run dev) and off in production; there is no PostHog flag. Override it with VITE_ENABLE_AGENT_DMS=true or false before starting Vite or building the frontend. Disabling discovery does not delete existing conversations or cancel their work.

Choose an agent in Create → Message, or click Message in its settings or bot profile. The picker offers your agents, eligible team agents, and Macro. Choosing an agent removes other recipients. Reopening the same persona returns to your existing private channel. Team ownership of an agent does not share your DM with teammates. Calls and additional participants are unavailable.

With the backend rollout switch enabled, the backing context stays out of the standalone Agents and Home session lists, including earlier contexts and contexts started fresh through the API. The DM remains in Channels/DMs. Opening its session by ID still works for an authorized reader, including streaming, questions, approvals, and Stop. Verify that an ordinary standalone session still appears in Agents/Home, the DM stays available in Channels, and reopening the DM resumes the same context.

DM session hiding has a separate backend rollout switch, initially disabled. Deploy the warm-marker migration and all updated harness replicas first; once no old warm reapers remain, set HIDE_AGENT_DM_SESSIONS=true for agent-harness-service and redeploy. New contexts are hidden immediately; a bounded startup/60-second backfill also hides existing contexts, including ones created by a replica still running with the switch off. The frontend discovery flag alone does not gate existing DMs or API callers. Until this backend switch is enabled, DM contexts retain their previous visibility. Before rolling back to code with the old warm predicate, restore DM visibility by reverting the migration before starting old service code; merely disabling the switch does not unhide existing contexts. Updated claim and cleanup require for_warming as well as hidden/unthreaded state, and exclude conversation reservations; genuine speculative sessions still expire normally.

Send normally: no @ mention is needed. Attachments, references, and quoted messages use the channel composer. While the agent works, a typing row sits under the newest message: the agent's avatar beside the working line, which names the step the agent is on, or says what the turn is doing (Thinking, Writing, Working, or Waiting for an answer) between steps and to anyone who cannot read the session. The owner also gets Stop on that row, which cancels the active turn, and any live question or permission request beneath it. Answer those controls to continue. If Stop fails, a failure toast appears and the control becomes available again so you can retry.

The reply is posted as ordinary messages while the turn runs. Each finished passage becomes a message, led by the steps the agent took to get to it, so nothing is posted until the agent has written something and no message shows a step running. Steps a turn ends on, with no passage after them (Stop, a failure), are posted with how it ended. The working line is one shimmering line, led by the working dots, naming the step in progress by its label alone, such as Ran, Read, Edited, or Searching; the command, query, or file stays in the session. The next step slides in as it starts, and steps running at the same time take turns every two seconds. In a DM it is the typing row. A channel mention's reply in its thread is one message, so the line sits in it, and reads Thinking whenever the turn is running with no open run, before the first step or while the agent writes after one. Once a run closes, it folds to a Used N tools summary (with · N failed when a step failed), with a caret after it on hover, that opens to compact rows like the session's tool rows: the label, and Failed or Interrupted when a step did not finish. Documents, sessions, pull requests, and contacts an agent's reply mentions are set in the accent color. Stored activity snapshots keep the status and label but omit commands and tool input details, in both shared threads and DMs. A view the agent presents (execution.views.present) is part of the reply: it is stored with its run and drawn after the run's line or summary, never folded into it, and each item it shows loads with the reader's own access. The line follows the session live while the run is open; the summary shows the snapshot saved in the message. Readers without session access always see that snapshot. Only the turn's last message notifies. Previews and search quote the passages, not the steps. Typing refreshes every 3 seconds and clears on its own if the agent's replica dies. Follow-up messages queue in order, and the bar above the composer counts them (1 queued). Editing a sent message does not invoke the agent again. A reply inside a thread is not part of the conversation: the agent answers it only when mentioned there, in the thread, as in any channel.

The local playground at /app/debug/agent-progress shows each of these states in three tabs: DM, Channel mention (the reply in its thread), and Agent session, with theme, viewer, and phone-width toggles and a looping replay of one turn.

Each failed, stopped, or interrupted source message has its own Retry message action in the current context. Retry is explicit because an interrupted attempt may already have performed an external action. Refreshing or reopening the channel does not rerun completed messages. A disconnected live display offers Reconnect without issuing another prompt.

The conversation has no control for resetting the agent's context; it continues in one context. A context keeps the persona instructions, model, tools, and permission choice it started with, across reconnects; later persona edits do not reach it. A harness operator can still revoke permission bypass. Contexts started earlier through the API stay marked by a divider before their first message.

If access to the persona is revoked or the persona is deleted, the transcript remains readable and the composer explains that the agent is unavailable. New prompts, retries, and answers to pending approvals require current access.

For rollout verification, cover a private persona, a team persona as two different users, simultaneous opens, queued follow-ups, reload during a turn (the typing row and live steps return without a duplicate reply), a multi-step turn whose steps tick from running to done, attachments, an inline question, an approval, and Stop/Retry. Check both desktop and a narrow viewport. Search the Channels view by persona name to reopen older DMs, including ones outside the currently loaded page. Harness traces use macro.event.type=agent_trigger.conversation_message and agent.session.id; the durable turn journal distinguishes queued, running, succeeded, failed, stopped, and interrupted attempts. Check completion latency, failed/interrupted turns, queue age, and duplicate source admissions during internal rollout. Model usage continues through the existing session metering.

Imported Slack history

Import starts from the Create or import channels card's Import Slack button at the bottom of the Chat sidebar, or Import on the Slack row in Settings → Integrations (team admins). The card's New channel button beside it opens the new channel dialog instead. The card is the shared connector-import card (see Import from connected apps) and is visible to team admins and owners when Slack archive import is enabled. It opens the shared import dialog: a Slack row connects through Pipedream, then Import from Slack hands channel picking to an agent chat in a split, and Import with history closes it and opens the archive upload below. Without an available Slack connector (Slack's Pipedream app is dev-only), the card opens the archive upload directly. Dismiss import from slack hides the card for that user on every device (see Dismissing cards); successful archive imports (including partial imports with a completed channel) and Settings channel imports also hide it. Failed or cancelled imports do not. Dismissing or completing an import keeps the Settings entry available; completion does not close an open progress dialog. Closing the archive dialog returns focus to the card's button when it is still visible. The dialog offers Import with history (recommended) and Import channels without history. The first needs a ZIP export provided by a Slack workspace owner or admin; its upload screen links to Slack's export instructions. Files and attachments are excluded. The second opens a dedicated channel import flow: it reuses an enabled Pipedream Slack connection or requests authorization, then automatically discovers public channels. Select channels and click Import N channels to create their names and matching Macro teammates. It requires no Slack admin role, but workspace app-approval policies still apply. Neither method sets up ongoing message sync. Previous ZIP imports are collapsed under a disclosure. Only explicitly selected Slack IDs create work. Slack public channels become Team channels with automatic team joining off; private channels and group DMs become Private. Two-person DMs keep exactly their mapped pair and never gain the importing admin as a third participant. Existing names, roles, leavers and newer activity are preserved. Imported history keeps source dates and does not produce live message notifications, invitations or bot invocations. Unknown authors display their Slack name through the system bot. Attachments and attachment-only messages are not imported. Cancellation keeps committed history; repeating an archive deduplicates source messages rather than applying later edits.

For verification, use synthetic local history with a root, replies and reactions. Search for an imported author name absent from the body. Verify the result for a participant and its absence for an unrelated viewer after indexing has caught up. Job completion means required search publication finished, not immediate index refresh. Test existing channel live activity is not moved backward.

Hover and click imported external links, channel mentions, root-message and reply references in the actual message body. Check destination channel/message/root UUIDs and that the correct message is revealed, including offscreen replies. Forward references must work regardless of conversation processing order. Prior same-source imports can resolve without being selected again; unselected targets must not be auto-created. Unknown Slack domains remain external links. Missing, skipped, deleted and inaccessible targets retain safe source-only fallbacks, and another viewer must not gain access through a rendered mention. Code examples remain literal; source-controlled tags must not inject entities. Test live edits and deletion before deferred reconciliation: neither may be overwritten or revived. See the rollout/recovery gates.

Collapsed reply chains

Collapsed channel threads show up to the first three replies from the timeline preview. New replies arriving while the channel is open must not enlarge that collapsed preview, even when they share a sender with earlier replies. Expanding shows the full thread; collapsing returns to the three-reply preview. The N more replies control counts individual hidden replies.

Check a long thread that receives replies while expanded, then collapse it: new replies must be hidden and included in the hidden count. Repeat while it is already collapsed, while its full replies are loading, and after scrolling the row out of view and back. Expanding again must retain every incoming reply.

Standalone thread previews show the first three complete message groups instead. Consecutive replies from the same sender within the five-minute avatar-grouping window count as one group. Different senders, longer gaps, deleted replies, and agent replies triggered by different users preserve their avatar group boundaries.

Channel timelines show system updates alongside messages: participant additions and removals, renames, profile picture changes, and completed calls with their duration. These rows have no reply, edit, or reaction actions. Long descriptions stay on one line; hover to read the full text. Dates, message navigation, and scrolling through older history include these updates. A call's completed row appears when the call ends; active calls retain their existing live indicator. To verify live updates, scroll into history and change the channel from another session. The visible message should stay at the same position. Return to latest and reload to verify that the system entry persists in chronological order. Also reload a short channel containing mostly system updates. Every entry should remain visible when the entire timeline fits without scrolling.

Agent session entities

The Agents list includes owned and shared sessions, except sessions started from a thread, which list only for people who prompted them from the session itself (see Home). Rows show the shared agent icon and session title; opening one navigates to /app/agent/<id>. The session title menu uses the shared entity actions: Favorite/Unfavorite and Copy link, plus Rename and Delete for the owner. Rename uses the shared rename dialog, not a session-specific modal. Folder moves, duplication, and property/tag editing are not offered because those APIs do not support sessions. Runtime controls remain session-specific.

A session transcript shows each tool call as a collapsible row (consecutive calls fold into a Called N tools group; click it to see the rows). A tool reached over an MCP server - Macro's own (ReadContent) from a Cursor, Claude, or Codex session, or a third-party server (ask_question) - is titled by the tool's own name, without a server or workspace label, never by the harness's dispatcher (mcp). Clicking the row expands the exchange: a Request section with the tool's own arguments and a Response section with what it returned, both as syntax-lit, pretty-printed JSON (prose results show as text), each with a copy button that copies the whole section; a call that failed is faded, shows the error as its subtitle, and adds an Error section. Rows for a call still running show whatever has arrived so far.

Inline image actions

An image attached to a channel message renders inline. Hovering it, or focusing it with the keyboard, reveals a small toolbar at its top right with Copy image and Download image, the same two actions the lightbox offers; it fades out when the pointer leaves and stays up while an action runs. Copy writes the full-resolution image to the clipboard (Copied to clipboard, or Copied image URL to clipboard when the browser refuses an image write) and Download saves it as image-<attachment id>.<ext> (Downloaded image). Clicking the image itself still opens the lightbox. Touch layouts do not get this toolbar: tap the image and use the lightbox toolbar instead. Videos have their own toolbar; see Downloading channel videos.

Reading channel attachments through MCP

When an agent reads a channel through Macro MCP, ReadChannelMessages, ReadChannelThread, and ReadChannelMessageContext include download URLs for image and video attachments, including attachments in replies and previews. Up to eight distinct images per response are also returned as inline images. Videos are linked for inspection with a video-capable tool. If an image cannot be loaded or exceeds the inline limit, its URL remains available. To check this, ask the agent to inspect an image on a channel message and a video on a reply; verify that its tool response includes the matching attachment URLs.

Messages sent through an MCP client

A message, comment, or thread reply a user's MCP client (Claude Code, Cursor, ChatGPT) posts through Macro MCP, with a direct tool such as SendChannelMessage or from code mode (ExecuteCode), shows the client as its sender: Claude Code · Agent with the client's initial as its avatar and a from pill underneath. The client is the name it registered with Macro's OAuth broker, or "MCP client" if it registered none. Notifications name the client as the sender too. A self-hosted agent's message shows the agent as the sender with from , and a message sent with a pasted Macro API key shows the Macro bot with from . To check this, connect an MCP client over OAuth, ask it to post in a channel and to comment on a document, and confirm both show the client and the user on desktop and at phone width.

Account manager requests

A DM between a person and an agent account has an account manager button (user-gear icon) in the channel top bar; a DM between two agents or two people doesn't, because an agent can't be managed and only an agent can manage. It starts a request: the person asks the agent to manage their account, or the agent asks to manage the person's. Either way a card appears in the DM (<m-account-manager-request>{"id":"<grant>"}</...>).

  • The side that didn't ask gets Approve and Decline. Approve opens a confirmation stating the access it gives. The side that asked gets Withdraw.
  • Approval posts a second card with a one-time link to /app/account-manager/<grant>. Reveal token on either surface works once, only for the manager, and shows the token in a dialog.
  • Requests and unclaimed approvals expire after 7 days. Revoke active access from Settings → Account Managers.
  • Messages the manager sends with the token show the managed account as sender, with a from <agent> line (triggered_by).

Message composer

Channel messages and thread replies have a microphone next to Send on pointer devices. It uses the same OpenAI Whisper dictation and scrolling volume timeline as AI chat. Use dictation appends text to the draft without sending; Cancel dictation or Escape preserves the existing draft. Sending is blocked during dictation, including keyboard and external send actions. Confirming uploads the in-memory audio to Whisper, which is available on all plans without consuming chat credits. Browsers without microphone recording show a disabled button. Touch devices have no microphone in either the collapsed or the expanded composer — their keyboards already dictate — so Send is the only control on that edge.

Composer and conversation body text use text-base (15px at the default root size) on desktop and mobile. The shared scale uses 14px for text-sm and 12px for text-xs, with accessibility text scaling preserved.

Desktop message text uses a 16px horizontal inset and a compact gap above the toolbar, consistent at narrow and wide composer widths.

The new-message compose screen and channel message/reply inputs use the same attachment and send controls on mobile and desktop. On phones, the + drawer offers Format text beneath Mention to toggle the formatting ribbon. iOS uses the native media attachment picker. In the iOS app, both collapsed and expanded channel inputs use the shared glass press spotlight. Tap the editor and its enabled actions to check the highlight; the caret, draft, keyboard, and action timing should remain unchanged. Flat embedded inputs keep their host's surface. Short top-level drafts place attachment, message text, and send on one row on both mobile and desktop. Text that wraps onto a second line, explicit line breaks, non-paragraph blocks (lists, blockquotes, headings, etc.), and attachments expand the composer with its actions below the editor. Even a short or empty non-paragraph block uses the expanded layout; converting it back to a single short paragraph restores the compact layout. A restored block draft that becomes a wrapping paragraph should stay expanded without briefly collapsing; check this after reopening the channel with a draft already saved. Open reply composers always place the editor above the action row, including for empty and single-line drafts, so the attachment, delete-reply, and send controls have their own space. Shift+Enter adds a line to the draft; Enter sends. The composer spaces its paragraphs the way the sent message does, so a multi-line draft reads as what it will send. Check a multi-line message against the draft that wrote it: the spacing must not change on send. Typing 6. then Enter (or 6. ) starts an ordered list at 6; the marker is not rewritten to 1. Both the expanded and collapsed composers start with a + button (Add). It opens a menu on desktop and a bottom drawer on mobile: Mention (opens the @ typeahead), Attach files (the file picker; the iOS media picker on iOS), GIF (the same picker as /gif), then under Create the same actions as /task, /poll, /form and /document (poll and form only with forms on), then Ask Macro (inserts an @Macro mention) and, in a channel, Start a call (Join call while one is live). On phones, starting a new call opens a confirmation sheet with centered participant avatars, notification copy, and a full-width green Start call button, without a divider or close/cancel buttons. Show up to four avatars including yourself. With more than four participants, show three unobscured avatars and overlay +N on the fourth; N includes everyone after the first three (five participants shows +2). Drag the handle, tap the backdrop, or press Escape to dismiss without starting a call. Only confirming notifies participants; joining a live call skips the sheet. Check both DMs and channels, including long names, in light and dark themes. On phones, a collapsed composer with attachments shows a thumbnail of the first one between + and the draft, with the number of attachments over it when there are two or more; a document shows its file icon. It shows with or without draft text, and tapping it opens the composer with the attachments below the editor. Check one image, several mixed attachments, and a document alone, with and without text, in light and dark themes. Input action and formatting buttons show the app tooltip without a second native browser tooltip. On phones, choose + → Format text beneath Mention to show or hide the ribbon above the editor, including in message and reply edits. It offers bold, italic, strikethrough, inline code, lists, checklists, and blockquotes; scroll the ribbon horizontally to reach all controls. Verify that selecting struck-through text, tapping Strikethrough, and saving removes the formatting while preserving the text. Toggling the ribbon keeps the draft and returns focus to the editor. Tapping the ribbon's padding or dividers also keeps the editor focused. On desktop, select draft text to open the floating formatting toolbar. Its compact frame uses 4px outer padding with concentric button corners, a white light-mode background, a thin border, and a soft downward shadow. Check Bold and the text-style dropdown in both light and dark mode. When checking this transition, type a long draft without pressing Enter, then shorten it and resize the pane. It should expand when the text no longer fits beside the buttons and collapse when it fits again, without flickering between layouts. Also add and remove a line break or attachment and confirm the draft and caret position survive. The attachment and send controls should remain usable in both layouts. Existing message and reply edit inputs show Add, Discard Edit, and Send on phones; desktop keeps Attach files in place of Add. Escape also cancels an edit. The iOS app uses its native media picker. Check inline and unified edits on desktop and touch: attach a file and save, then edit again and discard changes without changing the original message or attachments. The iOS share sheet keeps its editor above the attachment and formatting controls. Check this arrangement at both phone and tablet widths.

With a wrapping draft present, repeatedly narrow and widen the desktop split and window, then scroll the message history. The composer should settle into the matching layout without ResizeObserver loop completed with undelivered notifications errors. Resize-triggered wrapping measurements run in the next animation frame; draft edits still measure before their first paint.

On Android, tap @ on the software keyboard in an empty channel composer or after a space: the mentions menu should open above the keyboard. Type a name to filter, then tap a result to insert one mention without sending the draft. An @ inside a word stays literal text. Check hardware-keyboard input too; it should open only one menu. The same software-keyboard check applies to : for emoji and / for formatting commands: type a search and tap a result without sending the draft. Type /gif or choose GIF from +. The rounded picker replaces any active formatting or link menu, opens above the composer on phones, and stays visible after you choose the action, including with the iOS keyboard open. Both the / formatting menu and the GIF picker span the available chat width on phones, using the mentions menu's side gutters. If the browser has no caret selection or its range has no rendered geometry, the GIF picker anchors to its editor rather than staying hidden. The larger desktop GIF picker stays within the viewport on narrow screens. Repeat after scrolling the page: the picker must stay beside the composer, without adding the page's scroll offset to its fixed position. Open and dismiss the keyboard while the picker is open: it must recalculate its placement and available height. Focusing search must not scroll the page away from the composer. Trending GIFs show first, with the large search field focused on both desktop and phones. Search keeps the composer expanded, and tapping anywhere in the search field keeps focus there. Tap a GIF to download its original animated bytes and upload them to Macro's static-file service before insertion, without sending the draft. The picker shows upload progress and prevents duplicate selections; a failure removes the unused upload and leaves the picker open for retry. Closing the picker, changing the draft, or losing edit permission prevents a late insertion. Cancellation aborts the transfer and discards any completed upload that was not inserted. On desktop, arrow keys move through the two-column grid and scroll the full selection outline into view; Enter inserts it and Escape closes the picker. Check that GIFs animate in the picker, in the draft, after sending, after copying and pasting, and in the enlarged image viewer. Newly inserted GIFs use static-file references; picker previews and existing Klipy URL images still load directly with anonymous CORS.

Closed mention menus do not gather, rank, or paginate candidates. When checking channel-switch performance, include touch navigation back to the list and reopening a cached channel without typing @. Then open mentions, search, close, and reopen: results must reflect current people and entities, and scrolling or keyboard navigation must still load more results. Check both mobile and desktop.

The shared @ menu also offers Recent agent sessions after Channels and before Companies (the latest 500 accessible sessions, searchable by title or persona). These inline chips show the shared agent icon and an underlined session name, and open the existing session when clicked. They are references, not bot invocations: selecting a session does not start a new agent run. Sending or editing a message that references a session you own grants that channel/DM edit access to it. Non-owner references do not create grants. Access follows active membership; deleting the reference does not revoke the grant. Inaccessible sessions render a private/deleted label. Chips omit persona avatars and status; previews refresh periodically while the browser tab is active to update titles and access.

Placeholder Type @ to share with #<name>. Click it, type_text, press Enter to send. On touch devices, Send activates on release, not when pressed down. Holding or cancelling a press does not send; releasing outside the button keeps the draft. The composer keeps keyboard focus when sending. New local messages lift into place with a gentle settle on touch devices; history stays still and Reduce Motion disables the entrance animation. The message renders immediately with avatar, email, timestamp. Composer extras: Attach files and the Send message button. Replies also include a close-reply control.

Hover a message for its action menu. Reply on a top-level message opens that thread. On an existing thread reply, it inserts a one-line reply-target reference into the composer; clicking the reference navigates back to that reply. References to the current channel navigate in place, including inside the preview panel, without opening another split. If text in the message is browser-selected before Reply is clicked, the reference previews only the selected text. Clicking Reply again for a message already referenced anywhere in the draft keeps the existing reference and draft unchanged, even if a different text selection is used. For agent-session messages, the reference previews the resolved answer or current activity rather than the internal Magic Chip marker. Agent-session announcements use the same ReplyTarget reference for the prompting channel message; ordinary Markdown blockquotes remain presentation-only and do not count as replies. The composer always keeps an editable empty line after a block reference, including after the user deletes that line, so clicking below the reference can restore the text caret.

The mention menu offers a single @Macro; the enable-chat-v3-agents rollout decides whether it answers in the thread as the classic bot or opens an agent session. Without the rollout, @Macro answers in the thread (classic bot). Its tool calls execute immediately — there is no composer or pending-confirmation card in a channel, so asking it to create a calendar event without attendees creates the event right away (unlike AI chat, where creation waits for the user to confirm a composer card). For an event with attendees the bot is prompted to ask for confirmation in the thread first, since Google sends the invitations the moment the event is created — no invitation goes out from the initial request. It cannot draft or send email at all. A bot or agent reply posted for a person shares, as that person, the linked items (chips, attachments, or forms presented as cards in the reply's steps) that the replying bot created for them while answering: those with a created activity row by that bot on the person's behalf since the person's latest message in the thread before the reply, or, for a bot message that starts its own thread (a poll card posted top-level), their latest message in the channel. Forms and databases an agent creates through code mode (its SDK token) are attributed to its bot like native tool creations. Activity arrives asynchronously, so missing rows are re-checked after 5 and 30 seconds. Existing items it links, plain URLs, and bot posts with no person behind them share nothing. The bot never asks whether to share; it calls ShareWithChannel when asked to share an existing item. Private and confidential calendar events stay unshared, and a calendar event can only be shared by someone who holds it on their own calendar. The bot's prompt carries the current date and time in the mentioning user's own time zone (their primary calendar's), so it resolves relative times ("tomorrow at 4", "EOD") without asking; when no calendar is connected the prompt falls back to UTC and the bot asks before scheduling a specific clock time. Within the rollout, @Macro — plus @cursor / @codex when available — opens an agent session; follow-up @ mentions of that bot in the same thread route to it. An agent mentioned in a thread reply gets, on its first turn, the images and videos on the mentioning message and then on the thread root and earlier replies (at most 8, no duplicates); follow-ups carry only their own files. Files elsewhere in the channel appear only as <attachment> entries in its context. To check, post an image on a thread root, mention an agent in a reply without attaching anything, and confirm it describes the image. Macro Coding Agent (@coder) is unavailable in mention suggestions, including when it appears among existing participants or bots. Check with the agents rollout both enabled and disabled.

Agent-authored messages trigger other agents exactly like a person's: an explicit mention starts or continues the mentioned agent's session, and an unmentioned reply in a thread can reach another live agent there by quote-reply or inference. The originating user's permissions, connected runtime, and usage allowance apply through the bot message's server-recorded attribution. Autonomous webhook posts without that attribution trigger nothing, and a bot never triggers its own session. Finalized bot answers are evaluated like new posts, mentioned or not; streaming updates and ordinary edits are not. Agents handing the thread back and forth stop after 128 agent turns (64 round trips) with no person writing in between; the next agent message is logged and triggers nothing, before any classifier runs. The invoked session's prompt reads "Started by for " (or "Asked by" on a follow-up). To verify, ask session-backed @Macro to post a mention of @cursor, then have Cursor post a mention of session-backed Macro in the same thread. Check that the first mention opens Cursor and the return mention continues Macro's existing session. Repeat with revoked channel access and confirm no new work starts.

When the backend is configured with AI usage enforcement, a rejected classic @Macro request gets a thread reply explaining the allowance failure (for example, ai_allowance_exhausted) or temporary validation failure (ai_billing_unavailable), without a lingering thinking placeholder. This also applies in document discussions. Optional unmentioned follow-up inference, including attached-image descriptions, is skipped when admission fails; silence does not mean the request was approved. Explicit mentions and reply-target routing still reach downstream execution checks. To verify after backend wiring, test an exhausted account and unavailable billing: explicit classic mentions should show the failure, while unmentioned follow-ups should not generate responses. Repeat with an attached image. Enforcement is off by default; browser verification requires a configured backend.

A follow-up sent while that session is still working stops the current turn, posts a new Magic Chip on the follow-up message, and steers the agent with that text — the chip appears at the follow-up, not after the cancelled turn finishes. The reply renders a Magic Chip: a fixed 88px two-row card on desktop and mobile, including lazy loading. The header shows a leading status icon, agent name, model (hidden below 600px), an xs status badge, and an outlined Open session button (icon-only and circular on narrow cards). Working and tool calls use a slow Morph; lazy loading and queued states use a gray pulsing dot. Done uses a filled check circle, errors a warning circle, input requests a yellow question circle, and stopped a square. The lower row shows either a full-width PR preview with available line diff counts or one truncated line of agent output. Failure explanations replace that preview; tool commands and other secondary details stay inside the session. There are no tooltips. Click the card or Open session to read the full response or answer a question; click the PR to open its Macro split (GitHub until its entity has synced). While the synced PR is open, not a draft, and every check on its head commit has finished with a success, skipped, or neutral conclusion, a green Merge button sits at the end of the PR row. It asks Merge pull request? first, showing the title and repository/PR number in the shared confirmation dialog (a bottom drawer on phones). Cancel returns to the chip; Merge pull request merges on GitHub with your own linked GitHub account, so GitHub's permissions and branch protections apply; a refusal shows GitHub's reason as a toast, and success flips the chip to merged without a reload. Draft PRs, PRs with no checks, and PRs whose checks are still running or failing show no Merge button. Merged and closed PRs show no Merge button. Expanded session mentions retain their collapse control. The card never expands in place.

Built-in provider agents are offered before account setup, each within its own rollout: @cursor requires the enable-cursor-agents flag (local override: VITE_ENABLE_CURSOR_AGENTS), and @codex requires both enable-chat-v3-agents and enable-codex-agents (local override: VITE_ENABLE_CODEX_AGENTS). Outside a rollout the entry is absent from the mention menu and from task agent assignees, even when that bot is already a channel participant. Custom agents keep their channel visibility rules regardless of which harness they use. A mention without a connected account creates no session and replies in the thread with a Connect Cursor or Connect Codex chip. Each chip opens Settings → Agents → Runtimes, where the connection cards in the reader's rollout are visible. The same chip reads connected after setup; mention the bot again to start a session. Codex also prompts for a cloud environment when ChatGPT is connected but no environment has been saved. New sessions use that environment on main; there is no automatic repository selection. Follow-up mentions continue the same agent session. When the provider URL arrives, the session header offers Open in Codex. Codex assistant text appears as complete messages while tool activity and thinking can continue updating during the turn. Mention eligibility is covered by component/query tests; the channel interaction requires a configured backend for end-to-end verification.

Within the Cursor rollout, @cursor is offered whether connected or not. A mention from someone with no Cursor API key opens no session: the Cursor bot replies in the thread that @cursor runs on their own account and is not connected yet, followed by a Connect Cursor chip. Clicking the chip opens Settings → Agents → Runtimes; once a key is saved the same chip reads Cursor connected and stops navigating. The original mention is not replayed - mention @cursor again after connecting.

Cursor sessions choose a repository from the mentioning user's linked GitHub App installations on their first prompt. A session without a repository can still use Macro and connected MCP tools, but cannot use the Git proxy. For a PR smoke test, link the GitHub account and App installation in the same environment first, then name the repository explicitly in a new session's prompt.

PR status in an open Magic Chip updates from connection-gateway events after webhook sync. Reconnecting refreshes active PR lookups to recover missed updates. A late webhook does not require reloading the page.

When the agent requests permission or input, the Magic Chip displays the waiting status for its anchored turn. Open the session to answer; editors and owners can respond there. The chip follows the agent's next activity after the answer. A tool call explicitly acting as the session owner in a turn somebody else prompted, held for that owner’s approval reads Waiting for approval; only the owner approves it, in the session.

Coding agents use macro_internal.set_pull_request to register an existing or new GitHub PR with their session. Macro Internal MCP is hosted by the harness service at /mcp/internal on its egress listener, separately from workspace MCP. Cursor, sandbox, and macrod sessions receive session-scoped credentials; the model supplies only the URL. The tool records the link, not the GitHub PR itself, and returns the session's /app/agent/<id> URL. Macro Internal MCP's server instructions ask coding agents to register PRs with it, to link the returned session URL in the PR description (the PR block reads that link as the PR's origin), to open them ready for review rather than as drafts, and to get CI passing before handing off. External MCP clients get the ready-for-review rule in Macro's MCP instructions, and in-app agents tell coding agents they dispatch. It is not prepended to individual user messages. Cursor enables automatic PR creation when a repository is selected. Its returned URL is also recorded because automatic creation can finish after the agent stops. Repeated registration is idempotent. The PR URL is stored on the session row, independently of conversation history. Registration sends a session-update gateway notification so mounted chips reload the current link; reconnecting also refreshes it. Multiple chips for the same session share its metadata, and loading it leaves the surrounding editor visible.

When Cursor or Codex reports a pull request, the chip header shows its GitHub link. Codex links can arrive after the assistant finishes; a session-update event refreshes mounted chips without a new conversation message. Codex checks provider PR metadata every 20 seconds while attached. Viewing a disconnected Codex session reads saved history; sending a message reattaches the runtime. Refresh requires its original ChatGPT connection to remain connected. The link remains usable while the webhook mapping is loading or absent, then becomes a Macro PR entity link once synced. On narrow chips, long PR names truncate with an ellipsis; hover the link to inspect the full title. Codex delayed-link discovery, duplicate and changed metadata updates, and opening the exact PR URL were verified in Chromium with mocked session snapshots and realtime invalidation. This UI check does not prove live provider discovery; backend tests separately cover delayed provider metadata.

When an agent links its session to a task with macro_internal.link_task, the session header (and the side panel's Task row) shows a task chip before the PR chip: the task title, or Task while loading or without access. Clicking it opens the task in a new split (in place on touch devices). Linking a different task sends the same session-update notification, so mounted headers refresh. When the agent names that task in a reply — after creating or linking it, or later — the reply includes an <m-document-mention> task chip, not a URL or MACRO- id.

When the agent stops to ask a question the question takes the area in the passage's place, cropped and expandable the same way: the prompt, then what is asked - a form's fields (choice rows with an accent box, an Other row when the agent allows a free-text answer, text and number inputs, a yes/no), a URL request's host and address, or a Macro user tool's draft (SendEmail, CreateCalendarEvent) in the tool's own composer - the same email compose or calendar event form the session shows, editable in place; expand the area to reach its Send/Create, which answers with the edited draft. A row at the bottom of the area carries the other decisions, refusal first: Dismiss · Open in session for a tool draft, Decline · Submit · Open in session (or Open for a URL) for a question. Only the session's owner can act; other viewers see the question read-only and the header names who is being waited on. Once answered, the area shows the agent's passage again. A prompt the agent read out of a channel or document thread opens no review card at all: the reply writes the whole email or calendar event into the thread and asks whether to go ahead, and a reply in that same thread approving it ("yes, send it" / "go ahead") is the confirmation - the agent then sends or creates directly (SendConfirmedEmail and CreateConfirmedCalendarEvent, or in code mode macro.email.sendConfirmed, EmailMessage.forwardConfirmed, EmailDraft.send and macro.calendar.createConfirmed), with no session visit needed. Being asked to send or schedule something only produces the draft; nothing goes out before that approving reply. Images made with GenerateImage are saved to static file service. The bot embeds the returned URL as a Markdown image in its channel reply; generated images have no document mention or filename card. Agent replies may contain mention chips (<m-document-mention>) that render like any other channel mention. A mention of an image document (PNG, JPG, GIF, SVG, WebP) also unfurls beneath the message text as an image card: a header with the filename above the picture, inside the message's [data-message-mentioned-images] element. The chip stays; clicking the card opens the image document in a split. The same image mentioned twice unfurls once, mentions of other document types, channels, and chats never unfurl, and inaccessible images show nothing. This applies to every channel message, not only bot replies, so a person sharing an image document by @ mention sees the same card. The preview shows Preparing preview until storage has the bytes. With GraphQL enabled, document mentions and preview cards load in bounded batches, including task status/priority/assignees and the viewer's edit permission. Task badges can appear with the initial preview rather than waiting for separate properties/document-metadata requests; cached titles may appear first while those edges load. Ordinary document/task mentions do not wait for the built-in skills list. Built-in skill mentions retain their non-document behavior. The Magic Chip that streams the agent's reply stays inside the message column: long thoughts, file paths, and unbreakable tokens wrap or truncate instead of expanding the thread past the chat's right edge.

Message scrolling and navigation

Thread rails end at the last reply avatar when there is no inline composer or footer below it, including when the parent message was deleted. Grouped replies after that avatar do not extend the rail. On mobile (or with the unified composer), starting a first reply adds no rail to the parent; replying to an existing thread keeps its reply branches without a dangling composer segment. Desktop inline replies still connect to their composer.

Channels open at the latest message, with short conversations aligned above the composer. Incoming messages and growing replies stay in view while the channel is at the bottom. Consecutive sends stay pinned through server acknowledgement and composer resizing, without bouncing upward between messages. Scrolling up more than 1px leaves the viewport on the history being read, even when only slightly above the bottom. Composer and viewport resizing respect the same boundary. Returning to the bottom resumes following; loading older messages preserves the reading position.

On Safari and iOS, open or navigate near the oldest loaded messages and allow the history buffer to fill, then flick into older history. Loading should stop once roughly six screens are available above the viewport and resume as you approach that buffer. Check that pagination retains the visible message, and that latest stays pinned when messages arrive, images load, or the composer resizes. Verify message/reply navigation, restoration, and the custom scrollbar after pagination. Very long flings or slow responses can still exhaust the available scroll range. In the iOS app, fling repeatedly through a long channel, starting each fling before the previous one's momentum ends, then let it settle. The messages must not jump when scrolling comes to rest, nor when it bounces or is held against the top of loaded history. In a channel opened for the first time, fling up through unmeasured history and straight back down: scrolling must stop at the latest message, never in blank space below it.

Inline document mentions should show their stored title before entering the viewport and while preview requests are pending. With a slow preview response, check that a long, unchanged title retains its line wrapping as the preview loads; a renamed document should update to its fetched title afterward.

Message and reply links reveal the target inside its thread. Keyboard message navigation scrolls only when the selected message is outside the usable viewport. With a message selected, E edits your own message and does nothing on someone else's message. Check both root messages and thread replies from a Home split: an incoming selection must not mark the Home item done or edit the thread root. Press Escape to clear selection; the parent Home shortcut is then available again. Typing e in the composer or inline editor should still enter text. Verify a message link in a fresh browser tab as well as inside an open channel: the initial page should center the requested message, including older history. On a cold notification open, the destination shows the three-block Macro loader while channel metadata and the targeted message window load in parallel. It must not briefly fetch or display the latest messages before resolving an uncached message link. Explicit thread replies load their parent window and replies together; known root messages skip the message-kind lookup. Throttle these requests and verify the loader transitions directly to the target, without a blank body or message-shaped placeholders. A newer link supersedes an unresolved one, while a jump inside an already-mounted conversation preserves its composer. Returning through split navigation restores the saved message position and expanded threads. Switching channel tabs and returning restores the Messages position, expanded threads, and pending reply from when the tab was left. The Scroll to bottom control appears when scrolling down through history; it returns to the latest page even after opening a link into old history. On touch devices a round Jump to latest button sits bottom-right above the composer whenever the list is away from the bottom, in either scroll direction; tapping it smooth-scrolls to latest and keeps the keyboard open. The jump waits for that page to reach the rendered list. A newer message navigation cancels a pending jump to latest. Scrolling manually or choosing another destination also cancels the initial target's delayed fallback. A touch tap leaves pending navigation intact; a vertical finger drag cancels it.

The Unread notification chip navigates unread threads whose destinations are outside the viewport. A collapsed thread with hidden unread replies shows a dot and accent border on its show-replies control. While that control is visible, those hidden replies do not contribute to the floating chip; scrolling it out of view restores the chip, pointing toward the control. Expanded threads use actual unread message positions. A visible unread reply does not hide other offscreen unread replies in the same thread. There is one chip, targeting the most recently active eligible unread thread. Its count includes only distinct offscreen unread threads, not notifications. Three replies and a mention in one thread count as one; reactions do not count. Clicking the chip expands the target thread and reveals an unread message. Scrolling an inline indicator into view does not expand the thread or mark its hidden replies seen. Automatic read marking waits until the actual message intersects the visible scroll area, excluding floating header/composer insets. Offscreen overscan, collapsed replies, hidden panes, and background tabs remain unread. Expanded standalone threads and the thread side panel use the same visibility rule. New notifications on an already-mounted offscreen reply remain unread until that reply comes into view. Explicit notification clicks and mark-read actions retain their existing behavior.

Visibility is conservative: moving a partly off-window pane without crossing either observer's visibility threshold can leave a now-visible reply unread until the next intersection update or an explicit mark-read action.

The backend-free regression uses the real message read marker and channel virtualizer on desktop, phone, and tablet: bunx playwright test --config src/features/notifications/browser-test/playwright.config.ts. Check the last channel message with a long collapsed unread thread: at the bottom, the inline dot and accent border should be visible without a downward chip. With another unread thread above, an upward chip should remain and count only that offscreen thread. Scroll the disclosure out of view and back, expand and manually collapse the thread, and check composer/mobile insets. The indicator must appear even before full reply data loads. Check a target below the viewport, an unloaded parent, live notifications, and switching channels while notifications load. Loading this channel's notification edge must not delay its messages or activate the global GraphQL notification feed.

On native iOS, tapping a thread reply push in Notification Center or on the lock screen should open its channel, expand the parent thread, and reveal the actual reply. Verify with the app backgrounded and after terminating it. Use an older thread with a reply hidden by the collapsed preview so opening only the channel or parent message cannot satisfy the check. See the native notification regression procedure for simulator setup.

The [data-channel-scroll] element is the scroll surface. Its virtualized rows are keyed by message ID; offscreen rows are normally absent from the DOM.

On a cold channel open, verify that delayed bot/agent mention requests leave the messages and composer visible. Expand a thread while its replies are still loading: existing preview replies should remain visible until the full list arrives. Repeat after reopening the channel to cover both cold and cached data. For PR mentions, also fail a GitHub connection-status request, scroll through virtualized rows repeatedly, and verify remounts make no new status requests. An explicit retry or completed OAuth must still refresh the status, even if all mentions have unmounted or only disabled preview observers remain. Then paste a mention while the retry is held pending. The composer must stay visible and focused, and messages containing PR mentions must render immediately. Resolve the retry as linked, unlinked, or failed: none should hide the surrounding UI; only a confirmed unlinked/reauthentication status changes the chip to a link. After a confirmed unlinked status, fail a refetch and remount the mention: it must remain a plain GitHub link without hiding the surrounding UI. Scrolling a collapsed thread into view must keep its timeline preview unchanged, without fetching or revealing the full reply list. Cached replies from a previous expansion must not enlarge that preview either. Explicit expansion, replying, and message/unread-chip navigation may still open the thread.

Channel messages, thread replies, reactions, edits, deletions, and typing go through the shared message API at GET|POST /dss/messages/channel/<id> and its items, threads, and typing subroutes; the /dss/channels/<id>/message*, reaction, and typing routes no longer exist. Live updates arrive as one message_update websocket payload per committed change (posted, edited, message_deleted, reaction_changed, thread_updated, typing); the older comms_message, comms_reaction, comms_attachment, and comms_typing frames are no longer sent. Documents share the same client, cache, and components (see documents.md).

Reopening a cached channel, reconnecting its live subscription, or returning from an absence past the presence window revalidates its timeline with GET /dss/messages/channel/<id>/timeline?selection=<default latest-page selection>. This replaces stale roots and their reply previews, reactions, and edits, and removes deleted roots even when no newer top-level message exists. Loaded older pages are also refetched using the refreshed cursors. A committed live change restarts any in-flight channel timeline refresh, including when older pages are still loading, so its result cannot overwrite that change. Idle channels still apply live events without fetching; cached content stays visible if a refresh fails. Message links still load around the targeted message. The channel_messages_load event records path: full and reason (revalidate, no_cache, cache_not_at_latest, or load_around). Actual in-flight restarts emit a channel.timeline_restart span, searchable by channel.id. query.count records the number of restarted queries; query.fetch_more_directions and query.outcomes are arrays in the same query order (refetch/forward/backward and fulfilled/rejected). The span also records fulfilled/rejected counts and is marked as an error if any restart fails. Idle channels emit no restart span. Request error text and message content are not included.

To verify recovery, open a root with no replies, disconnect that client's live updates, then add replies and reactions, edit another root, and delete a root from a second client without posting a new top-level message. Reconnect the first client: the collapsed preview, reply count, reactions, text, and deleted row must all catch up without a reload. Repeat with older pages loaded and after a mobile background/foreground cycle.

Message reaction notifications

Message reaction notifications are enabled by default. The message author can turn them off with Message reactions in notification settings. Adding a reaction from another account notifies the author; self-reactions and removing a reaction do not notify.

In Home, reactions belong to the message's thread row: a top-level message uses its own row, and a reply uses its parent thread. Verify that an incoming reaction brings that row back into the inbox, displays the reaction and channel name, and opens the reacted-to message. Marking the row done should clear its reaction notifications along with the other notifications for that thread.

Requests to join

Opening a private or team channel you are not in shows You don't have access to this channel, the signed-in email, and Ask to join. Public channels are open to everyone, and direct messages offer no request. Sending shows Request sent with Withdraw request. After withdrawing, asking again waits a minute; after a denial it waits 24 hours, and the panel shows when.

The request appears in the channel timeline as " () asked to join the channel" with Approve and Deny for any participant. The name and full account email wrap at phone widths so reviewers can identify the requester before answering. If the display name already is the email, it appears only once. Every participant also gets a Requests to join notification (turn it off under notification settings) that opens the channel and marks it unread. The first answer wins: the row then shows Approved by or Denied by for everyone, a withdrawn request shows Request withdrawn, and the other participants' notifications are marked done. Approval adds the requester, who gets the usual "added you" invite notification, and the timeline shows the usual added row. A requester waiting on the denied view is taken into the channel when the approval arrives.

Verify with two accounts: ask from a non-member, approve or deny from a member in another tab, and check the row, the requester's view, and the member's inbox update without reloading. Check the panel, full requester email, and the row's buttons at phone width. Use a copied /app/channels/<id> link for a private channel absent from the requester's channel list. The Chat workspace must offer Ask to join there and open the conversation after approval. A transient loading failure still offers Retry rather than an access request.

Returning to a denied channel waits for that screen's fresh request read, even when an earlier request is cached or the read is paused offline. A missing channel shows Conversation unavailable with Retry, without cached request controls. Other request-read failures show an inline error and Retry. Retry and background metadata refreshes keep the current unavailable or denied screen in place until the result arrives.

Chat navigation rail

With no conversation open, the desktop Select a conversation pane shows the Chat TutorialPill (from features/video-tutorials) once that video is in its catalog; touch layouts, which have no detail pane, show it in the empty conversation list.

Following a channel mention or browser notification for the conversation already shown in Chat activates that workspace and jumps to the targeted message or reply. It keeps the shared channel detail mounted and does not show a Content already open toast. The same applies to a channel preview in Home; a closed channel opens normally. In Chat, the detail uses the shared channel top bar with Messages, Attachments, Participants, and Calls tabs (when calls are enabled). A message target switches back to Messages; changing unread notifications does not restart navigation.

On desktop, switching conversations selects and mounts the cached conversation immediately. Messages load alongside the notification refresh. Explicit message or search targets apply immediately; ordinary opens start at the bottom. Notification results never change the destination. With a slow connection, switch channels quickly: an earlier response must not switch back or mark that earlier channel read.

A transient notification-fetch failure keeps the conversation and composer mounted while notifications are unavailable. Recovery marks top-level message notifications seen without moving the conversation. No notification read marking runs from an abbreviated list result, even if that result is empty. Access failures and server-confirmed missing channels show Conversation unavailable and stay hidden during retry until access is confirmed. With GraphQL caching enabled, an empty local projection cannot hide a server-confirmed conversation; a stale positive row cannot undo a fresh denial or deletion. Contradictory cache membership triggers a bounded server confirmation. An initially empty cache result waits for that confirmation before declaring the channel unavailable. Unavailable routes still recover from invite notifications and reconnect without mounting a message view first. A route without cached channel metadata shows Loading conversation until its channel arrives. On mobile, opening from the Recent conversation list also navigates immediately: a slow or failed notification lookup must not prevent messages and the composer from loading. Full-edge notification hydration runs only after navigation is accepted; failure leaves unread state unchanged and must not show an “Unable to open conversation” toast. A late response must not reopen the channel or mark it read after the user leaves its mobile pane. Message loading retains its own access/error states. Verify with the notification request held, then failed, and with rapid back-navigation while it is pending.

The title bar's Hide navigation control hides the whole rail. Reopen it with Show navigation (the hamburger) immediately before the conversation title. Chat remembers this choice independently of other workspaces and restores it after reload. While no conversation is selected, the rail stays open regardless of that choice and offers no Hide navigation control (Cmd+. is inert); selecting a conversation applies the saved choice again. Chat uses the shared 256px default sidebar width and resize limits. In splits 720px wide or narrower, the rail and the conversation take turns at full width instead of a slide-over: with no conversation selected the rail fills the split (no Hide navigation, Cmd+. inert), and an open conversation shows Back (left arrow) where the hamburger was. Back opens the Channels list route, so browser or split back returns to the conversation. There is no separate skinny sidebar mode.

Sidebar redesign rollout

enable-chat-sidebar-sections gates the desktop layout, not channel or direct-message creation. It defaults on in development; deployed builds defer to PostHog. Set VITE_ENABLE_CHAT_SIDEBAR_SECTIONS=true or false to override it locally. Wait for the flag to resolve before mounting a desktop layout or loading its lists. An unavailable or disabled remote flag restores All, Recent, and Threads (the latter still requires enable-channel-threads-preview), the original independently scrolling groups, and separate creation actions. A saved Recent or Threads tab survives switching the redesign on and off. Personal-section queries and new section preferences do not affect the flag-off layout. Existing labels remain governed by enable-channel-tags. Mobile retains its recent feed regardless of the redesign flag, including while it is loading.

Original sidebar (flag off)

The desktop rail keeps All and Recent tabs in a shared pill track beside New. All contains optional Favorites and independently paginated Team channels, Channels, and DMs. Channels lists joined public and private channels. Each group collapses and sorts independently; open groups split the available height.

enable-channel-threads-preview adds a Threads tab. It is on in development; VITE_ENABLE_CHANNEL_THREADS_PREVIEW overrides it locally. All threads clears the channel filter, while the Conversations section lists channels and DMs with threads the user participates in. Scrolling loads more. Selecting a conversation filters the thread view instead of opening that conversation. On desktop, Threads pins navigation open with no Hide navigation control. In narrow splits the thread view fills the split like a conversation, and Back returns to All.

Sectioned sidebar (flag on)

With the flag on, desktop Chat has one conversation sidebar, without All, Recent, or Threads view tabs. The default order is Favorites, Direct messages, the team's channels, custom sections, then All channels. All channels lists joined public and private channels, including those assigned to manual or smart custom sections. The team heading is [Team name] channels, with Team channels as the fallback while its name is unavailable. The team section always shows joined team channels, including channels assigned to manual or smart custom sections. Each custom section is a top-level heading, independent of the Team channels disclosure. Empty sections use padded, bordered cards like saved views, with a subtle background and secondary actions; empty Favorites explains how to add a favorite. Private conversations use a lock icon in the sidebar and mobile feed, including favorited private conversations. All section headers use the shared collapsible-section styling without leading icons or top padding; the section stack supplies a compact 2px flex gap. Custom-section drop zones and highlights cover both the header and its content, including the empty state. Rejected drops show a borderless explanation; pending section data keeps drops disabled without covering the section with a loading message. Section, DM, and search containers use the 8px outer sidebar gutter; headings and rows add their own item padding so headings align with the Chat title. Rows are indented by 8px under every section, including Favorites, custom sections, and DMs. Empty-state actions and search results avoid this extra indent. The caret stays hidden in expanded sections until hover and remains visible when collapsed. Team-shared sections show a neutral Shared badge next to the name, before the caret. Below 256px of section width, a users icon replaces the badge to leave more room for the name. Separate short tooltips explain the name and sharing, without overlapping native title hints. Personal sections have no scope icon or badge. Header focus backgrounds fill the entire header row, including its trailing controls, with no extra right padding.

The sidebar uses TanStack Virtual for the section stack, each expanded channel list, and search results. Rows retain stable identities and measured positions through live refreshes and section reordering; focused and dragged rows remain mounted when they leave the visible range. Keyboard navigation scrolls immediately, without animation, only when the highlighted row enters the viewport's two-row context margin, leaving neighboring rows visible above and below. The margin shrinks in short sections. Section jumps also reveal the heading with surrounding context. Sections normally scroll independently. When All channels is last and has no manually saved height, it expands to its full content height and uses the sidebar's scroll area. Moving another section below it restores the usual height cap, without discarding a saved manual height. Lists with more than two items have a resize grip; drag it to choose a height between two rows (68px) and the end of the list, capped by the section's maximum. Shorter lists fit their content and have no resize grip. Favorites and Direct messages default to four visible rows; other sections default to their maximum height within the pane. Focus the grip and use Up/Down to resize by 20px (100px with Shift), or double-click to restore the default. Section heights persist as personal preferences alongside sorting and sidebar width. Heights adapt to filtered content and smaller panes without discarding the saved preference. Search covers channels and DMs regardless of section placement and restores the selected row in its section when closed. Mobile retains the recent-conversation feed below.

Drag a section heading, its name, or the grip in the left gutter to reorder sections, or focus the grip and use Up/Down. Pointer dragging starts only after more than 8px of movement, never from holding still. A normal heading click still toggles the section; releasing a drag does not. Add and menu buttons never start a drag. The bare grip appears only on header hover or keyboard focus and stays fixed when pressed, without its own button background. The drag highlight includes both the grip and section name without shifting the header's text or controls. An insertion line shows the destination. Section order is a personal preference, including for shared sections, and survives reloads. The dragged section appears as a card preview while its source is subdued. Other sections animate into their new positions on drop or keyboard reorder, except with reduced motion enabled. Dragging near the sidebar's top or bottom uses the same edge-scroll mechanism as Gantt; wheel scrolling remains available during a drag. Resizing near the sidebar's top or bottom also scrolls the sidebar, including while the pointer stays still. Resize drags compensate for that movement, and the rounded resize grips retain pointer capture until release or cancellation.

Section membership comes from the server's complete visible channel-ID lists. The sidebar shows available channel rows immediately. One shared by-ID query per batch supplies cached channel data and fetches only missing records using Soup's generic explicit-entity hydration. Channel batching and unread refreshes stay in the channel query layer; the sidebar does not coordinate separate cache and network queries. Each expanded section appends skeleton rows while its remaining channels load, using the same row indentation and icon/text columns as loaded channels. A failed fetch keeps available rows and replaces that section's loading feedback with Retry. Loading sections must not briefly show an empty-state hint. Collapsing a section hides its loading feedback without changing membership or stopping shared channel hydration. The header does not show a Loading sections/Retry strip during normal loading. Section reads use the shared bounded retry policy, retry on focus, and preserve cached sections during a refetch. A failed initial load retains a compact error and Retry action. Until section metadata is available, New section explains its unavailable state in the creation menu; ordinary conversations remain usable.

Favorites open the same channel detail as ordinary rows. A single click opens a row even when channel data refreshes between pressing and releasing the pointer; section and search lists retain row identity through those updates. Shift-clicking a favorite, channel, or DM opens it in a new split. Rejected navigation and failed hydration must not mark notifications read. Context menus retain Mark Read, Open in new split, Unfavorite, notification controls, and Copy Link.

Favorites defaults to Custom order. Drag a favorite onto another favorite to move it to that position; an accent insertion line shows the exact destination above or below the target row. The order saves through the shared favorites API and survives reloads. Hidden favorites and favorites of other entity types keep their positions. Sort → Custom order restores dragging after choosing an automatic sort. Releasing over a favorite preserves the drop target through scroll updates; releasing outside the list leaves the order unchanged. Dropping a favorite does not open its conversation or move it into a custom section. Failed saves roll back and show an error toast.

Sections

Sections reuse channel labels. The existing enable-channel-tags flag controls section management; VITE_ENABLE_CHANNEL_TAGS=true enables it locally. Turning the flag off hides section controls and stops label reads without deleting saved labels. Channel and direct-message creation remain independent of the label service and its feature flag.

Use New → New section to create a section. The wider dialog has a name field and a Smart section switch in its body. Shared with team sits on the left of the footer, with the action buttons on the right. The question-mark tooltip beside sharing explains that team members can see and organize the section and only team channels can be added; clicking or tapping the help button also reveals the explanation below the footer controls. The form shows a warning-colored Team channels only hint when sharing is on and no scope hint when it is off. With both switches off, the section is personal and manual. Smart grouping reveals a separate input below Name contains and a matching-channel count. Hover or focus that count to preview matched channels; larger results show the remaining count. Switching sharing scope refreshes the preview without replacing the form. A zero shared count explains that only joined team channels match; public and private channels remain personal. Edit and delete through each section's sliders menu. Editing also exposes Shared with team. Turning it on or off preserves the section ID; turning it off requires confirmation and makes the section personal to the current account, removing it from teammates' sidebars. The toggle is disabled with an explanation while channel eligibility is loading or when any current member is unavailable or ineligible for the destination scope. No channels are silently dropped. Personal sections are private to the account, including for team members, and accept joined team, public, or private channels. Shared sections accept only channels from that team. Any current team member can create, edit, change sharing, or delete a shared section; these actions are not admin-only. Neither kind accepts DMs. Scope changes reject duplicate destination names and atomically move manual assignments into the destination scope, replacing other manual assignments there. Smart sections keep their rule and reevaluate matches in the new scope. Ordinary channel assignments stay isolated between personal and shared scopes. Names are unique within each scope, case-insensitively.

Each heading has one sliders-icon menu, also available by right-clicking the header. Sort opens its independent single-select options with a checkmark on the right. Filter contains Unread only. The unread label sits on the left and its switch on the right; toggling it keeps the submenu open. Manual sections have a + header action and Add channels menu entry. The picker searches all eligible joined channels, not just rows loaded in the sidebar, and excludes channels already in the section. The wider, shorter picker keeps its actions visible while the channel list scrolls. Compact helper text explains the scope and assignment move. Adding a channel moves its manual assignment within the same scope without changing the other scope. Partial failures keep successful additions and retry only the failed selection. Empty manual sections offer Add channels, empty smart sections offer Edit rule, and unread-filtered empty sections offer Show all channels. Custom sections also include editing, Mark all as read, notification actions, and a destructive Delete action in the same menu. Click and right-click menus use the same standard context-menu rows, spacing, and selection indicators. Use the heading's caret to expand/collapse it; this is not repeated in the menu. There is no separate all-sections management menu. Sorting and unread filters are personal, even for a team-shared section. Date ordering follows each paginated source; Favorites and custom sections also offer A–Z. Filtered-out channels retain their membership and do not reappear ungrouped. Shared name and rule edits apply to the team; personal edits affect only the account. Deleting a section does not delete its conversations or change channel access.

Every desktop section menu, including Favorites, [team name] channels, and Direct messages, offers Mute all channels, Unmute all channels, and Snooze all channels. These update only your notifications, including for shared sections. Each action uses the section's complete current membership, including filtered-out and unloaded channels; channels added later do not inherit the change. Built-in lists resolve all pages before applying an action and never include unjoined channels. The team section includes its custom-section members. Favorites targets only channel favorites, not documents or other favorite types. Snooze uses the usual duration/date picker and resumes notifications at the chosen time. A partial failure keeps successful updates and reports the failures; snooze retries only failed channels. Mute, unmute, and snooze submit up to 500 item preferences in one atomic backend request, rather than one request per channel. Larger selections use sequential requests. The frontend applies confirmed changes in one cache update, preserving unrelated preferences and successful requests if another fails. Empty or unavailable custom sections and empty Favorites disable these actions. Mobile remains unchanged.

Use a channel's Add to section menu to change the personal or shared assignment. Each section uses a checkbox: checking moves the channel into that section, and unchecking removes it. Only one section per scope is assigned; the personal and shared assignments remain independent.

Choose smart grouping in the section dialog for automatic name matching. Smart sections match channel names literally and without regard to capitalization. They preserve ordinary section permissions and are not manual drop targets. Channels can appear in multiple matching smart sections. Loaded same-team channels join matching shared smart sections immediately, including after a rename; they do not wait for the next section refresh. If a channel's team metadata is missing, only an existing server-authorized match is retained. Channels from another team never become new local matches. Hovering an incompatible item over a section shows a not-allowed cursor and an explanation over the section, including automatic membership, shared-scope restrictions, and channels already in the section. Returning a channel to its matching built-in channel group removes only its existing manual assignment.

Support is organized manually through a personal section. The app does not classify support channels by their names or silently create a Support section.

Verify personal and shared creation, same-name sections in different scopes, private-channel assignment, and rejecting private-channel assignment to a shared section. Check collapse and reload, stale requests after an account change, empty sections, assignment failures, and one channel in both scopes. Check the New menu, both dialog switches, keyboard access, edit-dialog focus, destructive deletion, and per-section unread and sort preferences after reload. Confirm unread filtering does not change section membership or another section's rows. Scroll a long sidebar with many sections, reorder both custom and built-in sections, and confirm the order survives reload. Keyboard navigation and section shortcuts must follow the same order as the rendered rows. Drag a channel between sections and confirm the sidebar stays visible while lookups refetch, including with a slow or paused connection. When a channel belongs to both a personal and a shared section, drag its personal-section row into the ungrouped list. Only the personal assignment is removed; the shared assignment remains. Repeat from the shared-section row to verify the opposite scope.

Creation actions

The sidebar's New dropdown spans its button's full width. New offers separate New channel and New direct message actions in both sidebar layouts. New channel opens the existing name, visibility, and optional invitations flow. New direct message opens the existing recipient picker, including people, external email addresses, private groups, and available agent personas. The sectioned sidebar also offers New section in the same menu.

Check each creation action with the sidebar flag on and off; changing the layout must not change the creation flow.

When calls are enabled, Live appears below the rail's toolbar while an active quick call is available. It stays visible while browsing sections and during conversation search, and disappears when no active quick calls remain. Entries are titled Call with <creator's name>. Clicking a call opens its camera/microphone setup at /app/meet/join/<token>; it does not join immediately. Live rows use the shaking incoming-phone icon, respecting reduced motion. The Channels navigation phone indicator appears for active channel calls or active quick calls visible to you. This list includes calls you own, joined, or were invited to during the current live session. Declining or letting the incoming popup expire stops ringing but keeps that active call available here. The invitation does not carry forward to a later session of the same reusable call link. Leaving and rejoining keeps the row available while another participant remains. When everyone leaves, the session ends; reopening its link starts a new session. If a restored Chat selection is already open in another view, its preview stays closed but the saved selection is retained. Close the other view, then select the conversation again or reopen Chat to restore its preview. Verify that an unrelated rail preference change while blocked does not erase the saved selection. While reading older history or composing in the preview, incoming notifications (including ones for other channels) must not jump to latest, blank/refetch the messages, or revoke composer focus. To check this, leave an unsent draft in a preview scrolled into older history and deliver a notification. Selecting another conversation or explicitly navigating to a message must still work. The sidebar search action expands a field under the title. Search results replace the section list with compact conversation rows and preserve the selected channel. Closing search restores the section list and scrolls to that selection when available. Search merges the complete joined-channel list with authorized service results, deduplicates by channel ID, and retains loaded unread metadata. Clearing the query restores ordinary pagination.

Each primary channel list and the DM panel keeps its own persisted sort: last viewed, last updated, or date created. Custom section channels follow that section's selected sort, defaulting to alphabetical order. Loading failures show Retry without hiding already loaded rows. Loading another page must preserve keyboard focus and scroll position.

Arrow Down / j follows visible rows, including section headings. h / l collapse or expand the focused section. [ / ] jump between primary and custom section headings, including the DM heading. Paging at the last loaded channel retains focus until the next page arrives. From a custom-section heading in the middle of the list, use both [ and ]; each shortcut must move to the adjacent heading rather than the Team channels heading.

On touch layouts, Channels shows only the Recent conversation feed, with channel and DM message previews. Rows use Home's touch row: the unread dot in the left rail, a 44px avatar, and a divider inset to the text column. The first six favorited channels (favorite order) are pinned in a three-across grid above the feed, iMessage style, and leave the feed below; tapping a pin opens it and a hold opens its action menu, where Unfavorite unpins it. There are no view tabs or reserved tab-header space; older saved tab selections and mobile-tab links cannot change the list. It loads more as the list approaches the end and supports pull to refresh. Rows use the same touch highlight as Home and Email: taps retain feedback while opening, holds stay highlighted for the action menu, and scrolling or cancelling a touch clears the press highlight. The mobile dock Search button opens the independent Search route. Its Channels and People categories search the complete channel list, cached channel names, and people directly; the conversation list does not constrain results. Full-text search is explicit, and People uses the existing channel-content scope. Closing search resets its session; the conversation list retains its browse pagination. See Search for mode, keyboard, and session-reset checks. With enable-graphql-soup enabled, open an unread conversation from the mobile list and return to the list: all notifications on top-level messages should be seen, including mentions and reactions older than the global feed's loaded page. Replies and mentions inside threads remain unread. Channel-view unread badges only represent top-level messages and mentions; unread replies and reactions do not contribute to that badge. Top-level reactions are still marked seen on open. Verify an older unread root behind a newer reply still badges. Inbox retains its own thread-stack behavior.

Each ordinary conversation click opens the bottom, including re-clicks, shift-clicks, mobile opens, reloads, and favorites. Explicit search hits and message links still open their target. Each accepted click marks top-level notifications from the full loaded edge seen; an abbreviated list edge is never sufficient. A rejected selection or unavailable split must not mark the conversation read. Non-participant rows retain their membership status and do not mark notifications. Shift-click and the row menu's Open in new split open a loaded row without waiting for notifications: hold the single-channel SoupNotifications request (UPDATED_AT, limit 1) and the split must still appear at once. Its full edge loads after the open. A failed load leaves the split open and skips that marking; messages on screen still mark themselves read as they become visible. Shift-click a favorite whose channel is not loaded in the rail: its membership and full notification edge load before the split opens with the same top-level read policy. Selecting another channel while that request is pending must cancel the pending open; failed lookups must not open a split or mark anything seen.

With GraphQL enabled, the app-shell Chat badge uses ChannelUnreadPresence: only channel IDs and at most one unread top-level message/mention ID/state per channel, with a 500-channel candidate bound and no history, message previews, or metadata. It excludes replies, thread mentions, and reactions, matching the channel-row badges in both GraphQL and REST modes. It shares the channel lists' refreshes after notification patches, mark-read, and reconnect. Merely rendering that badge, subscribing to realtime notifications, or applying local read/done overrides must not start the full SoupNotifications feed. Check this with document-mention notifications disabled too (the production default): mention cleanup must wait until a real data/status reader activates the feed, then continue cleaning up loaded mentions. Full notification selection and pagination remain unchanged. Automatic/debounced read markers log failures and leave failed reads unread; they must not produce unhandled promise rejections or block the separate email read marker. Cold bulk actions wait for loading and report failures rather than treating pending data as an empty list. The Inbox badge still uses its own full Soup query for channel/thread membership.

With GraphQL enabled, channel lists request at most one unread message notification per channel through an aliased, filtered notifications edge. An empty edge means no unread messages; invites and call notifications do not light the dot. Recent cards still use the latest-message preview. Full notification edges load only for an opened unread conversation, so mark-read and message targeting retain their complete top-level inputs in Chat and thread-scoped inputs in Inbox. Reopening a conversation must refresh that full edge even within 30 seconds; mark-read waits for the refresh rather than using older cached notifications. Failed server lookups and successful server lookups with no matching channel show Conversation unavailable with Retry, never permanent loading. Retry rather than marking just the one unread witness. Repeated mobile taps must open the last selected conversation, not a slower earlier request.

A backend-free cache regression runs on desktop and phone viewports: bunx playwright test --config src/lib/queries/channel/browser-test/playwright.config.ts. It uses the production normalized exchange, query adapter, and detail state with a controlled transport. Confirm a channel, type a draft, then deliver repeated empty cache projections: the composer must remain mounted. A fresh server absence must hide it, a cached positive row must leave it hidden, and a fresh grant must recover it. See the desktop fixture and phone fixture; these show synthetic data, not a full app session.

Opening also refreshes that channel's bounded unread edge in the same request. Read a DM on another device while its web sidebar retains an unread dot (for example, with the read-status websocket update withheld), then open it on web. The dot and DM unread count must clear without reloading, even when the complete unread response is empty and no mark-read mutation runs. Another unread DM must keep its dot.

Check cached Home → Chat navigation, section browsing/search, and unread state after a read, a new notification, deletion, and reconnect, without reloading the page. With the mark-read response delayed, channel/DM dots, section counts, and new-activity targets should clear as soon as the local read is applied. A failed read restores them; a stale unread response for that same notification must not relight them. A different unread notification must still light the dot. With the normalized cache enabled, a new channel message notification writes its unread relationship and adds the channel to the cached Chat badge page locally. Delay the following HTTP refresh: the channel dot and Chat badge must appear before that response, without a reload. Also test an initially empty badge page, duplicate deliveries, multiple channels, and a notification arriving during a read. The local write must not replay other channels' read states. Invites, calls, and already-read notifications must not light message dots. Background refreshes still reconcile the bounded edges and recover missed updates on reconnect; an unavailable/cold cache falls back to the network path. These updates must not activate an otherwise-unused full notification feed. Cache reads remain asynchronous: a brief spinner can still appear, but cached rows must not wait for a background network refresh. Conversely, cache-and-network refreshes must start without waiting for a busy cache worker. Successful foreground query results display before cache persistence finishes; a delayed acknowledgement must not replay old rows or overwrite an optimistic update. Check initial and continuation pages with a slow cache, overlapping refreshes, and leaving/reopening Chat during a write. A cache write failure must not discard successful network rows. Mutations and cache-only hydration still wait for their durable/cache-projection work. A late cache snapshot must not replace newer network rows. Check a cold offline open too: a cache hit arriving after the network failure must remain usable without erasing the refresh error. If more unread notifications remain, the limited edge must refresh to the next one rather than staying empty. Refreshing unread indicators while composing must preserve the conversation, scroll position, and input focus. To check stale-cache recovery, mark notifications read/done in another tab, then repeat the action in a stale tab. Empty or partial changed-row responses must still reconcile mounted Soup and notification readers, without resetting loaded pages or starting an unused global notification feed. With the normalized cache, a Done writes the rows it left out as done (confirmEntityNotificationsDone), and a mark seen that left out a row the tab showed unseen reads every reader again; otherwise only readers the cache does not maintain are read again. Undo must use only the mutation's returned IDs, not IDs from the subsequent refresh. The backend must support the new edge arguments before deploying the frontend that requests them.

Call lifecycle

The active-call panel above the composer, the channel's call tab, and floating call controls share one session. Joining from the panel switches the current channel surface to the live call. Repeated Join clicks while connecting should produce one connection; leaving from either control ends the same call. Navigate away and return while connected to check that the call and its controls remain usable.

The Open chat button at the bottom-right opens chat beside the video. Copy Meeting Url sits at the bottom-left on desktop and becomes icon-only in narrow panes. Active phone calls keep the channel header island and place Copy Meeting Url in a matching header island using the shared CopyButton. The media control bar fills the space beside the separate chat button, below the video and within side insets. Back keeps the call running. Controls and header islands stay visible; idle auto-hide is disabled. Phone calls hide the app's bottom navigation and channel Invite action; Invite returns when leaving the live call tab. Tap or click a participant to focus them and tap again to return to the grid; speakers have an accent border. The panel has a Call chat heading and spans the full call content height, including the media controls row. The controls stay centered under the video on wide panes. In narrow desktop panes, chat overlays the video. On phones, chat opens in the shared bottom sheet; drag the handle, tap the backdrop, or press Escape to dismiss it. On desktop, Close chat or Escape closes the panel. Closing returns focus to the chat button, and reopening preserves the draft and scroll position. The call continues while chat is open or closed.

Signed-in participants in channel, quick, and scheduled calls use the same chat panel. Guests in quick and scheduled calls can also open chat and read and send text without signing in. Guest authors appear as Name (Guest). Their composer uses Enter to send on desktop and the Send button on touch devices, preserves drafts on close, and keeps failed messages available to retry. Guest chat refreshes while open and is available only while that guest is connected to the call. Check a signed-in participant and a guest exchanging messages in both directions, then verify the guest loses access after leaving or after the call ends. Guest messages remain in the saved call discussion. Each call session has one persistent message thread; signed-in participants use the shared message composer, attachments, reactions, and message actions. The @ menu offers Macro and available owned and team agents. Mention an agent and send to invoke it in the call thread; follow-up mentions use the same thread. Reply on your own or another participant’s message inserts a quote into the bottom composer while preserving its draft and attachments. Enter sends; subsequent messages and quoted replies join the same thread. Clicking a quote highlights its message in the live chat; Shift-click opens its durable saved-call link. Participants see new messages without reopening the panel. Check simultaneous first sends from two participants, edit/delete/reaction updates, a retained unsent draft after toggling chat, and a new incoming message while scrolled into history.

After the call ends, its recording page shows a read-only Call chat below the transcript. A copied chat message link opens /app/call/<callId>?call_message_id=<messageId> and highlights that message in the recording's chat. Clicking the highlighted message clears the target from the pane's route while leaving chat expanded; verify this on standalone and Drive recording pages. A transcript search result clears any earlier chat target in that pane. In an already-open Home call preview, follow a second message link and then open the call without a message target: the highlight must move to the second message and then clear without remounting the preview. After following a message link, scroll away and follow that same link again: the view must return to the message. Check repeated links in Home, Drive, and standalone recordings, and repeated quote clicks in live chat; navigation must preserve the mounted thread and any unsent draft. A new call in the same channel starts a separate thread.

An initial missing thread means the call has no messages yet. If a later chat refresh reports the thread missing or access denied after messages loaded, show the retry error and hide the stale thread. Verify that it never shows the empty-conversation prompt alongside cached messages. A transient server error may retain readable messages; Retry restores the thread when access and the request recover.

For recovery checks, keep another participant connected and briefly interrupt the first participant's network. Recovery may rejoin that same live call. It must not start a replacement call if the original ended, or rejoin after the user chose Leave. A failed join must restore the Try again control even if background cleanup is slow.

If another call prevents joining, the error should say to leave the current call first. Trying to join another channel must keep the current call connected, with its participants and controls intact. A restored live session must clear any earlier join or recovery error. Failed Join, Call Again, and Leave actions must not produce unhandled promise rejections.

On iOS, ending a call during connection must leave Join usable. If CallKit restores or answers another call while an earlier join or leave finishes, the controls must follow the current native call; finishing the old operation must not restore the old call or remove the new call's end handler. An empty native snapshot before the first media update must not cancel a new join. Once native has reported the session, disconnecting or ending it must cancel pending connection/recovery and allow a new join. Cancelling after a token is issued must also remove server membership, even if media has not connected yet. Repeated end events share that cleanup; a newer native call must survive while cleanup for the cancelled attempt finishes. Restore the same channel while transport cleanup is pending and check that no server leave is sent for the restored session. Join must also accept a retry during cancellation cleanup. If a server leave was already sent, the retry shows Connecting and waits for that request before registering again.

Channel tabs

Private and team channels show an Invite button on the right of both the split header and the inline conversation header for current participants. On mobile it renders as its own floating glass pill next to the Call pill (the split header is pointer-events-none, so the button must sit in a HeaderIsland to be tappable). Click it to open Invite people to <channel> using the standard dialog at the top of the viewport, matching the create menu and create-channel dialog (a drawer on mobile). Choose Add all members of <team> to add current teammates once, or Add specific people to search teammates and enter external email addresses using the same recipient picker as channel creation. Existing channel members are excluded. Add submits; Cancel, Close, or Escape dismisses without sending. Failed additions preserve the selection for retry. The team option is disabled when no team is available. This action does not enable team auto-join. Check opening and reopening, switching options, keyboard recipient selection, external email chips, cancellation, and focus restoration before sending invites.

Inset tabs sit in the channel header: Messages / Attachments / Calls / Participants. Ask Macro, Invite, and Call actions remain in channel headers, with the live-phone-call exceptions described above. On narrow desktop panes, the tabs collapse from text labels to icons. Standalone mobile channels keep view selection in the title menu. In both a single channel and an adjacent channel split, the message composer stays fully visible at the bottom. The Calls tab lists recordings for that channel (same rows as the Calls soup view, filtered to this channel). The live Call tab appears while a call is in progress. Ask Macro opens a new chat pane with the channel already @mentioned as context (see ai-chat.md). On mobile it lives in the channel title's ... drawer instead. Clicking the radio input can time out — click the adjacent label text instead.

In the Chat workspace — and wherever a channel opens inline inside another view's detail stack (a channel mention followed from the email view, say) — the conversation renders an inline detail whose top bar holds the channel avatar and name, the same inset tab strip, live viewer avatars, and the Call and Ask Macro buttons. An ellipsis follows the name — after the breadcrumb where the host supplies one, as in Home — and opens the same entity actions as right-clicking the conversation's rail row: Open in new split (when available), Rename, Set channel picture, Remove channel picture (only when the channel has one), Favorite/Unfavorite, Snooze notifications…, Mute notifications, Remind me, Copy Link, Copy ID. A channel can therefore be favorited or given a picture without finding its row, from Chat and from every view that opens one inline. The menu appears once the conversation itself has loaded, reusing a cached conversation without another activation fetch. Opening the conversation still refreshes its unread notifications. The split's own title ... menu offers the same picture actions.

Calls tab: recordings, transcriptions, and summaries for this channel. Click a row to open the call. The search field above the list matches call names and transcripts in this channel; queries shorter than 3 characters are not sent. Empty copy: No calls in this channel. No matches: No results for "…". Shorter queries: Keep typing to search.

Leaving from the channel's call controls switches to Messages immediately. Disconnect and server cleanup continue after that switch; slow or failed RTC teardown must not leave the channel showing the join screen.

In a live call, controls stay centered beneath the participant area when chat opens beside it. Microphone, camera, and background controls each have an icon button on the left and a settings caret on the right, separated by a divider. The icon toggles the feature; hover previews settings and the caret pins them. Check both chat states and narrow layouts, including Escape and keyboard focus in settings. Camera-off tiles use a subtle gradient from the profile picture's average color; missing or unreadable pictures keep the neutral panel background.

Participants tab keeps people and bots within the available page height, with separate scrolling lists and fixed search/invite controls. Team access appears between them when available. Search uses the shared input group; add, invite, and new-bot actions use neutral outline buttons. The bots section stays compact with few or no bots. Search by display name, email, or role and clear the search to restore the list; scrolling a long member list must leave the bots section and participant controls visible.

Participants tab:

  • Copy invite link, participant search box.
  • Add: combobox Add participants by name or email + Add Participant button.
  • Dividers frame the Add Participant controls, not the scrolling list. Each row shows the display name above the email, both on a single truncated line without text tooltips, and a title-cased role badge on the right. Click anywhere on the row or focus it and press Enter to open the DM; Shift-click opens it in a new split.
  • The separate Remove participant button never opens the DM (owner and current user show Cannot remove participant, disabled).
  • Team access: Team channel switch (disabled until you belong to a team).
  • Bots: New bot, Search bots by name or handle combobox, Invite bot — webhook-powered channel participants.
  • Bot rows match participant rows: name above a truncated handle/description, a Bot badge, and a row link that opens the bot. Copy webhook and Remove are separate actions that do not open the bot.

On touch devices, this page uses People / Bots / Settings bubble tabs. Bots appears when bot management is enabled; Settings appears for channel owners and admins when team settings are available. People keeps search and the compact Copy invite link / Add participants buttons above a virtualized scrolling list. Add participants opens a bottom sheet; Bots has its own full-height list and an Invite bot sheet. Bots uses the same search toolbar and plain rows as People; Search bots filters existing bots by name, handle, or description, with compact New bot and Invite bot actions beside it. The fallback New button is hidden throughout this page and returns when leaving it. Channel views have no floating AI composer. Both sheets use the standard mobile keyboard-aware layout and close after a successful add. Check switching tabs, closing/reopening both sheets, and scrolling a long participant list above the bottom dock, with and without the keyboard open. An invite-bot request from the channel menu opens the Bots tab and its invite sheet.

Incoming call ringing

For cross-tab ringing checks, sign the recipient into two tabs and start a call from another account. Both tabs may show the incoming call; only one should play the chime. Closing the audible tab lets the other take over while the call is still ringing. Answering or dismissing stops ringing across tabs. An unanswered call stops ringing after 30 seconds, including after a tab takes over.

Declining is per user and per device set, not per tab: the sidebar X and the rail Decline button send POST /call/record/{call_id}/decline, and every other signed-in device of the same user (other browsers, the iPhone's CallKit ring) stops ringing via call_declined. Declining on the iPhone lock screen does the same for the browser. Other channel members keep ringing, and the call stays active for them. Closing only the browser notification toast silences the chime without declining.

Onboarding channel

New users get Macro Support x <name> seeded with a welcome message that @mentions them — useful as a guaranteed-existing channel in tests.

Locally sent channel messages and thread replies enter with a brief upward slide and fade, without bubble scaling. Opening history or remounting a row does not replay the effect. Reduced-motion preferences disable it. Consecutive messages from the same sender should enter in their grouped layout, without briefly showing an avatar/header and collapsing after acknowledgement. Check this with a delayed send response in both the channel and a thread, sending each follow-up within five minutes of a confirmed message with no replies. Messages from different senders, including bot messages triggered by different users, should retain separate headers.

For mobile send regressions, keep the software keyboard open and send several short and multiline messages consecutively. The keyboard should remain open, the cleared composer should retain focus, and a pinned chat should remain at the bottom through composer resizing and server acknowledgement. Check that restoring the caret after send does not pan the page while the keyboard resizes. Repeat with the keyboard's own dictation and check that sent text does not return. Scroll into history before an incoming message or acknowledgement and verify that it does not pull you to latest.

For composer cleanup, repeatedly open and leave channels and threads, then switch between touch and keyboard/mouse input. Retired composers must not keep reacting to input-modality changes. Memory-pressure crashes still require an iPhone run with the app's native memory diagnostics.

Channel pictures

Channels and group chats can have a custom picture. Anyone who can Rename a channel can also set its picture: any active participant of a named channel, from the channel's rail context menu, the Chat title ellipsis, or the split's own title ... menu. Direct messages can be neither renamed nor given a picture. Choose Set channel picture to add or replace a picture. Select a PNG, JPG, WebP, or GIF up to 16 MB. The upload must finish before the picture is saved; the server accepts only supported images uploaded by the person setting the picture. An error leaves the previous picture in place. When a picture is set, the menu also offers Remove channel picture to restore the standard channel icon. The picture beside the title is display-only and also appears in shared channel rows. Picture changes refresh other participants' open sessions, including after reconnecting. A team channel the viewer has not joined shows its picture without editing controls. One-to-one direct messages continue to show the other person's user picture.

Opening the slash menu with / lists Normal Text, headings, and the other Markdown options before Query and Database. Typing /query filters to the Query action; /database creates a new database and inserts its editable card.

When Databases is enabled, type /query in a channel message or thread reply and choose Query to insert a live question. Ask with Enter or the Ask button, then accept the answer before sending the message. Enter in the question box belongs to the question and must not send the channel draft. Recipients can read the live answer subject to their database access. Database @ mentions in message composers remain compact; Expand turns one into an editable database card.

Downloading channel videos

Video messages show Download over the player on hover or keyboard focus; the control stays visible on touch devices. There is no footer below the video. The expanded viewer has the same action. These retrieve the original bytes and filename from static-file metadata; they do not record or transcode playback. If the metadata is unavailable, the fallback extension comes from the response MIME type. Linked video preview cards also offer Download, using the document's current version, name, and file type. See Downloading files for progress, cancellation, retries, and mobile save/share verification.

Opening or reopening the expanded video viewer focuses the video. Press Space to pause or resume immediately. Tab moves through the native player controls and viewer actions; focusing Download explicitly still allows keyboard downloads. With the video focused, Escape closes the viewer and returns focus to the thumbnail that opened it.

Pending message drafts

Sending clears the composer immediately while delivery is pending. If delivery fails and the composer is still empty, its text, mentions, and attachments return. A new draft typed during delivery stays intact if the earlier send fails. Verify this with both the Send button on a phone and the desktop composer.

For tab performance QA, switch Attachments → Calls → Participants → Messages in both the routed channel and a block split. Each actual selection should produce one channel.tab interaction with its channel.*.view child; repeat the current selection and confirm it does not create a new interaction.

Work in a DM with an agent account

Behind enable-agent-work, a 1:1 DM shows the other account's registered work when that account is an agent (isAgentAccount) and has work you can open. The rule lives in features/agent-work/core/work-visibility.ts. DMs with people, group DMs, and channels show nothing.

The side panel toggle appears in the top bar only while there's work, using the floating SidePanel the agent session uses. When the agent goes from no work to some, a " started working" label appears beside the toggle for six seconds without opening the panel; clicking it opens the panel. Clicking a row opens the session in a new split. Rows keep their order as state changes.

To exercise it, register a session as the agent account through the SDK (session.registerAsWork()), share it with the viewer, and watch the DM update live. session.unregisterAsWork() removes it. A registered session the viewer can't open stays hidden.