Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

62.2 KB
Raw Blame
/**
 * The Swarms a Harness Pro shows as cards on Home: for each Swarm (Super Tab) this account is in, one Lead per project with
 * what it is doing now, plus the last thing a Lead said, for the Pro's recap. Read as the person (never as an agent) from
 * the same backend routes the desktop uses, every 5 s while a capable Pro is attached (`want`); while the server pushes Swarm
 * changes, the list only when told and every 2 minutes (CARDS_SAFETY_MS). A tab's detail is read
 * only when its `lastChangedAt` moved, by what changed since the last read (superTabs/swarmReads.ts). The service hands the
 * result to the core whole (`onCards`); the core owns the wire.
 *
 * Status of a project's Lead, most pressing first: `ask` (an assignment of the project needs a person, `needs_human`),
 * `stuck` (`blocked`), `work` (an agent of the project, the Lead or a worker, runs here and is in a turn, as the app marks each
 * agent working by its own live turn, `since` from the earliest of those turns; or an assignment works or is in review, all there is for agents on
 * other machines), else `done`.
 * A paused Swarm keeps its card and every Lead reads `done`.
 *
 * For the round dial (design 2026-10-28-round-dial-swarm-chat) every Lead also carries the chat on its project's face (`chat`):
 * the Lead conversation, or the reader's Buddy chat or group the window has open (`want`'s focus); and the newest tag of the
 * reader's in its project since the baseline (`notice`), the dial's one alert: PM messages that tag nobody never alert (Diego,
 * #2965). `state` keeps its meaning for the Pro and older dials, which never read either.
 */
import { createHash, randomUUID } from 'node:crypto'
import type { BackendNotice, CoreApi } from '../core/api.js'
import { backend, SuperTabHostError } from './host.js'
import { identifier, object, within } from './wire.js'
import { SwarmReads, type SwarmRead } from './swarmReads.js'
import { buddyAvatar } from './buddyAvatar.js'

type Json = Record<string, unknown>
/** The cards' shapes are the core's contract with the Swarm (core/api.ts), which the core declares and the Swarm imports. */
import type { CardChat, CardFocus, CardSide, ChatKind, LeadNotice, LeadRecap, LeadState, SaidOnCard, SwarmBuddy, SwarmCard, SwarmChat, SwarmLead } from '../core/api.js'
export type { CardChat, CardFocus, CardSide, LeadNotice, LeadRecap, LeadState, SaidOnCard, SwarmBuddy, SwarmCard, SwarmChat, SwarmLead } from '../core/api.js'

const MAX_CARDS = 16, MAX_LEADS = 12, NAME_BYTES = 48, RECAP_BYTES = 1500, MAX_LIST_PAGES = 10, MAX_RECAPS_IN_FLIGHT = 2
/** The tag ids kept per Swarm as seen: the server lists at most 500 of a person's tags there (backend mentions.ts tagRows). */
const MAX_TAGS_SEEN = 500
/** The digest of no waiting tags (backend mentions.ts mentionsDigest([])): a Swarm at it has none to read. */
const NO_TAGS = createHash('sha256').update('').digest('base64url').slice(0, 16)
/** The longest a dial's recap read waits on the one before it. */
const ASK_WAIT_MS = 10_000
/** The Pro keeps an id in 48 bytes with its NUL: 47 characters at most reach it. */
const ID_BYTES = 47
export const cardId = (v: unknown): v is string => identifier(v) && v.length <= ID_BYTES
const ORDER: Record<LeadState, number> = { ask: 0, stuck: 1, work: 2, done: 3 }

/** Cut on a character, never inside one: the Pro refuses a string it cannot read as UTF-8. */
function cut(text: string, bytes: number): string {
  let out = '', used = 0
  for (const char of text) {
    used += Buffer.byteLength(char)
    if (used > bytes) break
    out += char
  }
  return out
}
const list = (v: unknown): Json[] => Array.isArray(v) ? v.map(object) : []
const projectKey = (project: Json): string => String(project.id ?? 'lead')
const inProject = (conversation: Json, projectId: string): boolean => (conversation.projectId ?? 'lead') === projectId
/** A Buddy chat (backend buddies.ts), where the PM's private lines land since Buddies replaced Chat with PM (10-29). */
const isBuddyChat = (conversation: Json): boolean => conversation.kind === 'buddy' || conversation.kind === 'swarm-buddy'
/** A person's one Buddy chat for the whole Swarm (backend buddies.ts, Dee 10-31): it has no project, so no project's id
 *  finds it. Since #2447 it is where the reader's Buddy lives, and a card that looked only in its own project lost the
 *  dial's Buddy side (Diego, 11-02). */
const isSwarmBuddyChat = (conversation: Json): boolean => conversation.kind === 'swarm-buddy'
/** A Chat with PM: a private conversation with an audience that is not a Buddy chat. Read-only once Buddies are on
 *  (backend commands.ts `PM_CHAT_READ_ONLY`), so words spoken to it on the dial would only be refused. */
const isChatWithPm = (conversation: Json): boolean => conversation.audience != null && !isBuddyChat(conversation)
/** The chat kind of a notice raised in conversation `conversationId` of a project whose Lead conversation is `leadId`: `lead`
 *  in that conversation, `pm` in the reader's Buddy chat or a Chat with PM, `group` elsewhere. Tags and decisions both. */
const noticeChat = (state: Json, conversationId: string, leadId: unknown): LeadNotice['chat'] => {
  if (conversationId === leadId) return 'lead'
  const conversation = list(state.conversations).find(c => c.id === conversationId)
  return conversation && (isBuddyChat(conversation) || isChatWithPm(conversation)) ? 'pm' : 'group'
}
/** The reader's own: the backend sends a Buddy chat to its owner alone (read/views.ts `groupView`), and the dial checks it
 *  again, so another person's Buddy chat never becomes a face, a buddy block or a notice whatever a read holds. */
const isReadersBuddyChat = (conversation: Json, me: string | undefined): boolean =>
  isBuddyChat(conversation) && me !== undefined && conversation.buddyOwnerId === me
const sequenceOf = (conversation: Json): number => typeof conversation.lastMessageSequence === 'number' ? conversation.lastMessageSequence : 0
const idsOf = (v: unknown): string[] => Array.isArray(v) ? v.filter((id): id is string => typeof id === 'string') : []

/** The reader's live Buddy chat for a project, when its id is one a dial can hold: their one Swarm Buddy chat when the Swarm
 *  has given them one (every project shares it), else their Buddy chat in that project, as older Swarms keep it. Another
 *  person's chat is neither, whatever a read holds. */
function buddyChatOf(conversations: Json[], projectId: string, me: string | undefined): Json | undefined {
  const live = (c: Json) => isReadersBuddyChat(c, me) && c.archived !== true && cardId(c.id)
  // Of several (task #3818), the reader's default: the chat the backend marks so, else the first.
  return conversations.find(c => isSwarmBuddyChat(c) && live(c) && c.buddyDefault === true) ?? conversations.find(c => isSwarmBuddyChat(c) && live(c))
    ?? conversations.find(c => !isSwarmBuddyChat(c) && inProject(c, projectId) && live(c))
}
/** The reader's Buddies in their chat: the chat's agents that are a Buddy of the reader. One whose `buddyOf` names someone
 *  else (an agent id reused or misfiled) is not, and neither is a thread session (spec 2026-10-30-buddy-thread-sessions),
 *  which answers in its own thread: the dial's Buddy is the main one. */
function buddiesIn(agents: Json[], chat: Json, me: string | undefined): Json[] {
  const ids = idsOf(chat.agentIds)
  return agents.filter(a => typeof a.id === 'string' && ids.includes(a.id) && me !== undefined && object(a.buddyOf).personId === me
    && (a.buddySession === undefined || a.buddySession === null))
}
/** The name Desktop shows and draws an agent by (super_tabs/identity.dart). */
const agentName = (agent: Json): string => String(agent.displayName ?? agent.name ?? '')

type Face = { conversation: Json; kind: ChatKind }
const leadFace = (lead: Json): Face | null => cardId(lead.id) ? { conversation: lead, kind: 'lead' } : null

/** Today's face of a project (a round dial without swarmBuddy): the conversation the window has open when it is a live
 *  conversation of this project, else the project's Lead conversation; null when that one's id is not one a dial can hold.
 *  The reader's Buddy chat reads `pm`. An archived group is over: the face stays on the Lead (Ruling on the plan,
 *  2026-10-28), and so it does for another person's Buddy chat and, while Buddies are on, a read-only Chat with PM. */
function faceOf(conversations: Json[], projectId: string, lead: Json, focus: string | undefined, me: string | undefined, buddies: boolean): Face | null {
  const open = focus !== undefined && focus !== lead.id
    ? conversations.find(c => c.id === focus && inProject(c, projectId) && c.archived !== true && cardId(c.id)) : undefined
  if (!open || (isBuddyChat(open) && !isReadersBuddyChat(open, me)) || (buddies && isChatWithPm(open))) return leadFace(lead)
  return { conversation: open, kind: isBuddyChat(open) ? 'pm' : 'group' }
}
/** A swarmBuddy dial's face: the reader's Buddy chat in the project, and nothing else, whatever the window has open (task #3908: people
 *  talk only to their Buddies). Null where the reader has none there: the dial says "No Buddy here yet". */
function buddyFaceOf(conversations: Json[], projectId: string, me: string | undefined): Face | null {
  const buddyChat = buddyChatOf(conversations, projectId, me)
  return buddyChat ? { conversation: buddyChat, kind: 'buddy' } : null
}
/** Whose messages are the chat's recap: the Lead's in its conversation and, for an older dial, in the reader's Buddy chat
 *  (its private lines); the reader's Buddy's on a swarmBuddy dial's Buddy face; the group's agents' in a group. */
function voicesOf(face: Face, leadId: string, agents: Json[], me: string | undefined): Set<string> {
  if (face.kind === 'buddy') return new Set(buddiesIn(agents, face.conversation, me).map(a => a.id as string))
  if (face.kind !== 'group') return new Set([leadId])
  return new Set(idsOf(face.conversation.agentIds))
}
/** The reader's Buddy in a project as a dial draws it, from Desktop's pattern for its whole name. */
function buddyOf(agents: Json[], chat: Json, me: string | undefined, local: (a: Json) => string): SwarmBuddy | undefined {
  const [found] = buddiesIn(agents, chat, me)
  if (!found) return undefined
  const name = agentName(found), here = local(found)
  return { chatId: chat.id as string, name: cut(name, NAME_BYTES), engine: String(object(found.configuration).engine ?? ''), ...buddyAvatar(name),
    live: typeof found.downSince !== 'string', ...(here ? { local: here } : {}) }
}

/**
 * One Lead per project of the Swarm, most urgent first with ties in the app's project order; the 12 most urgent are kept, and
 * each carries its project's place in that order as `order` (gaps where a project has no Lead or was cut), which a dial swipes
 * by. The app's order is by name, case-insensitively A to Z (desktop super_tabs/project_sidebar.dart: the sidebar and
 * superTabSidebarOrder), ties in server order: the two must match. `live` says whether this machine's core has a
 * harness and whether it is in a turn (null: not here); `me` is the signed-in person's id, so a Lead on someone else's
 * machine names that owner (people[] has an email, which is the name a Swarm shows a person by).
 */
export function leadsOf(state: Json, machineId: string, live: (harnessId: string) => { inTurn: boolean; since?: number } | null, me?: string, focus?: string): { count: number; leads: SwarmLead[] } {
  const agents = list(state.agents), conversations = list(state.conversations), people = list(state.people)
  const buddies = state.buddies === true
  // An old tab has no `projects`: its one project is the tab itself, `lead`, led by the conversation `lead`.
  const projects = Array.isArray(state.projects) ? list(state.projects) : [{ id: 'lead', name: state.name, leadConversationId: 'lead' }]
  const paused = state.paused === true
  // An agent's project as the app's roster reads it: its own, else the first group that has it or that it leads.
  const projectOf = (a: Json) => typeof a.projectId === 'string' ? a.projectId
    : conversations.find(c => (Array.isArray(c.agentIds) && c.agentIds.includes(a.id)) || c.leadId === a.id)?.projectId ?? 'lead'
  const turnHere = (a: Json) => a.machineId === machineId && typeof a.harnessId === 'string' && a.harnessId !== '' ? live(a.harnessId) : null
  const leads: SwarmLead[] = []
  // Compared by code unit, as Dart's String.compareTo; Array.sort is stable, so a tie keeps server order.
  const named = (p: Json) => String(p.name ?? '').toLowerCase()
  const places = new Map(projects.map((p, i) => ({ p, i })).sort((a, b) => named(a.p) < named(b.p) ? -1 : named(a.p) > named(b.p) ? 1 : a.i - b.i)
    .map(({ p }, place) => [p, place]))
  for (const project of projects) {
    const order = places.get(project)!
    const lead = conversations.find(c => c.id === project.leadConversationId)
    const agent = lead && agents.find(a => a.id === lead.leadId)
    if (!agent) continue
    if (!cardId(agent.id) || !cardId(project.id ?? 'lead')) continue
    const harnessId = typeof agent.harnessId === 'string' ? agent.harnessId : ''
    const here = agent.machineId === machineId && harnessId ? live(harnessId) : null
    const waits = new Set(conversations.filter(c => (c.projectId ?? 'lead') === (project.id ?? 'lead') && c.archived !== true)
      .map(c => object(c.assignment).status))
    let state: LeadState = 'done', since: number | undefined
    if (!paused) {
      if (waits.has('needs_human')) state = 'ask'
      else if (waits.has('blocked')) state = 'stuck'
      else {
        // The project's clock is its earliest turn here (the most seconds in), the Lead's or a worker's.
        const turns = [here, ...agents.filter(a => a !== agent && projectOf(a) === (project.id ?? 'lead')).map(turnHere)].filter(t => t?.inTurn)
        if (turns.length) {
          state = 'work'
          const secs = turns.map(t => t!.since).filter((v): v is number => typeof v === 'number')
          if (secs.length) since = Math.max(...secs)
        } else if (waits.has('working') || waits.has('review')) state = 'work'
      }
    }
    const ownerId = agent.machineOwnerId
    const owner = me && typeof ownerId === 'string' && ownerId !== me ? people.find(p => p.id === ownerId) : undefined
    const projectId = projectKey(project)
    const chatOf = (face: Face | null): SwarmChat | undefined => face ? faceChat(face, String(agent.id), agents, me, turnHere) : undefined
    const chat = chatOf(faceOf(conversations, projectId, lead, focus, me, buddies))
    const buddyChat = buddies ? buddyChatOf(conversations, projectId, me) : undefined
    const sideChat = buddies ? chatOf(buddyFaceOf(conversations, projectId, me)) : undefined
    const buddy = buddyChat && buddyOf(agents, buddyChat, me, a => turnHere(a) && cardId(a.harnessId) ? String(a.harnessId) : '')
    leads.push({
      id: String(agent.id), projectId: String(project.id ?? 'lead'), project: cut(String(project.name ?? ''), NAME_BYTES), engine: String(object(agent.configuration).engine ?? ''),
      owner: owner && typeof owner.email === 'string' ? cut(owner.email, NAME_BYTES) : '',
      local: here && cardId(harnessId) ? harnessId : '', state, order, ...(since !== undefined ? { since } : {}), ...(chat ? { chat } : {}),
      ...(sideChat ? { sideChat } : {}), ...(buddies ? { buddies: true as const } : {}), ...(buddy ? { buddy } : {}),
    })
  }
  // Equal urgency keeps the app's project order.
  const ordered = [...leads].sort((a, b) => ORDER[a.state] - ORDER[b.state] || a.order - b.order)
  return { count: ordered.length, leads: ordered.slice(0, MAX_LEADS) }
}

/** A face as the dial names it. Only a group works on the dial, and only while its assignment works: Lead, PM and Buddy
 *  chats never do (design decision 4). A Buddy face is named for the reader's Buddy, or plainly while it has none. */
function faceChat(face: Face, leadId: string, agents: Json[], me: string | undefined, turnHere: (a: Json) => { inTurn: boolean; since?: number } | null): SwarmChat {
  const { conversation, kind } = face
  const working = kind === 'group' && object(conversation.assignment).status === 'working'
  const voices = voicesOf(face, leadId, agents, me)
  const turns = working ? agents.filter(a => voices.has(a.id as string)).map(turnHere).filter(t => t?.inTurn) : []
  const secs = turns.map(t => t!.since).filter((v): v is number => typeof v === 'number')
  const [buddy] = kind === 'buddy' ? buddiesIn(agents, conversation, me) : []
  const name = kind === 'lead' ? 'Lead' : kind === 'pm' ? 'PM' : kind === 'buddy' ? (buddy ? cut(agentName(buddy), NAME_BYTES) : 'Buddy')
    : cut(String(conversation.title ?? ''), NAME_BYTES)
  return { kind, id: conversation.id as string, name, working, ...(secs.length ? { since: Math.max(...secs) } : {}) }
}

/** Where a message is looked for: anywhere in the page, or in the chat's main stream (a top-level message, one from before
 *  threads, or a thread reply also sent to the chat: backend catchUp.ts `inMainStream`). */
export type MessagePlace = 'any' | 'chat'
const isIn = (m: Json, place: MessagePlace): boolean => place === 'any' ? true
  : typeof m.thread !== 'string' || m.thread === m.id || m.alsoInChat === true

/** The newest row one of the chat's agents wrote: a person-visible message, not a system row (`source`), the person's or
 *  another agent's, in `place`. `at` in seconds; `id` the message's, or '' when it has none; `thread` the root of the thread
 *  it replies in when it is in that thread only. */
export function lastAgentMessage(messages: Json[], agentIds: ReadonlySet<string>, place: MessagePlace = 'any'): { text: string; at: number; id: string; sequence: number; thread?: string } | null {
  let best: { text: string; at: number; id: string; sequence: number; thread?: string } | null = null
  for (const item of messages) {
    const m = object(item)
    const author = object(m.author).id
    if (m.source != null || typeof author !== 'string' || !agentIds.has(author) || typeof m.text !== 'string' || !isIn(m, place)) continue
    const sequence = typeof m.sequence === 'number' ? m.sequence : -1
    if (best && sequence <= best.sequence) continue
    const stamp = typeof m.createdAt === 'number' ? m.createdAt : Date.parse(String(m.createdAt))
    best = { text: m.text, at: Number.isFinite(stamp) ? Math.floor(stamp / 1000) : 0, id: typeof m.id === 'string' ? m.id : '', sequence,
      ...(isIn(m, 'chat') ? {} : { thread: m.thread as string }) }
  }
  return best
}

interface TabCache { lastChangedAt: number | null; state: Json }
/** A recap read. */
interface Cached { sequence: number; recap: LeadRecap }
/** A Lead some Harness Pro has the recap of open, and the sessions (one per Pro) that have it open. With `chat` (a round dial
 *  that speaks `swarmChat`, or 'buddy' for one that speaks swarmBuddy), the recap is that dial's face chat's, and `chatId`
 *  the chat it was last told of. */
interface Opened { tabId: string; leadId: string; chat: CardChat; chatId: string | null; sequence: number | null; sessions: Set<string> }
/** Where a recap is read, or talk is posted: a conversation, how far it has gone, and whose messages are its recap; `buddy`
 *  when it is a swarmBuddy dial's Buddy face, whose notice is the Buddy's. */
interface Target { id: string; sequence: number; voices: Set<string>; chatId?: string; buddy?: true }
const recapKey = (tabId: string, leadId: string, chatId?: string) => chatId === undefined ? `${tabId}:${leadId}` : `${tabId}:${leadId}:${chatId}`
/** A recap's cache key: an older dial's and a swarmBuddy dial's recap of one Buddy chat hear different voices. */
const cachedKey = (tabId: string, leadId: string, target: Pick<Target, 'chatId'>, chat: CardChat) =>
  `${recapKey(tabId, leadId, target.chatId)}${chat === 'buddy' ? ':buddy' : ''}`
/** Spec 2026-11-02-poll-cost Part 4.3: the list was read every 5 s whatever changed (prod 2026-11-02: about 200 list reads a
 *  minute). While the server says it pushes this account's Swarm changes (`swarm_changed` naming none, repeated every 4
 *  minutes: backend lib/swarmClientPushes.ts), the list is read when a Swarm's main parts change, and after this long as the
 *  net for a lost push. The lease is Desktop's (super_tabs/controller.dart kSwarmPushLease). */
export const CARDS_SAFETY_MS = 120_000
const SWARM_PUSH_LEASE_MS = 5 * 60_000
const tabOf = (read: SwarmRead): TabCache => ({ lastChangedAt: read.lastChangedAt, state: read.state })

/** How long the first list waits for a Swarm whose read failed, before going without it. */
const UNREAD_HOLD_MS = 60_000

export class SwarmCards {
  onCards?: (cards: SwarmCard[]) => void
  onRecap?: (recap: LeadRecap) => void
  private readonly now: () => number
  private readonly intervalMs: number
  private readonly log: (line: string) => void
  private timer: NodeJS.Timeout | undefined
  private busy = false
  private tabs = new Map<string, TabCache>()
  /** The tabs to show, in the list's order, with the name the list gave each, as the last poll read them. */
  private rows: Array<{ id: string; name: unknown }> = []
  private recaps = new Map<string, Cached>()
  /** When each local Lead's current turn began, so `since` counts on between polls. */
  private turns = new Map<string, number>()
  /** Whether a harness is here and in a turn, as the last poll read it; null before the first. */
  private live: ((harnessId: string) => { inTurn: boolean; since?: number } | null) | null = null
  private last: string | null = null
  /** The first list is held back: a Swarm in it could not be read yet, and a list without it tells the dial that Swarm went. */
  private holding = false
  private unreadSince: number | null = null
  /** When each shown Lead's clock started (ms, `${card}/${lead}`), as the list last sent said. */
  private lastStarts = new Map<string, number>()
  private me: string | undefined
  private include: string[] = []
  /** The conversation the window has open in a Swarm tab: that project's face follows it. */
  private focus: CardFocus | null = null
  private opened = new Map<string, Opened>()
  private openBy = new Map<string, string>()
  /** Background reads of recaps and notices in flight, at most MAX_RECAPS_IN_FLIGHT. */
  private recapsRunning = 0
  /** The dial's own recap reads, one at a time and apart from the background's: a dial is never refused its recap. */
  private asking: Promise<unknown> | null = null
  /** One push of open recaps at a time: a focus change and a poll that both see a new face push it once. */
  private pushing: Promise<void> = Promise.resolve()
  /** The alert baseline: per watched conversation (`${tab}:${conversation}`), the last sequence whose messages were seen. */
  private seen = new Map<string, number>()
  /** Each Lead's newest notice (`${tab}:${lead}`), a tag of the reader's in its project, carried on its card. */
  private notices = new Map<string, LeadNotice>()
  /** The tags baseline: per Swarm, the mentions digest last read, and the ids of the tags seen waiting since the baseline. */
  private tagDigests = new Map<string, string>()
  private tagsSeen = new Map<string, string[]>()
  /** The decisions asked of the reader, as the tags: the digest last read and the ids seen. */
  private decisionDigests = new Map<string, string>()
  private decisionsSeen = new Map<string, string[]>()
  private personal = new Set<string>()
  /** Each Lead's newest quiet notice from the reader's Buddy (`${tab}:${lead}`): apart, so it never hides the Lead's. */
  private buddyNotices = new Map<string, LeadNotice>()
  /** Watched conversations whose last read failed, so a run of failures is logged once. */
  private failed = new Set<string>()
  private readonly reads: SwarmReads
  /** Until when the server is known to push Swarm changes, when the list was last read, and whether a change since asks
   *  for it again. */
  private pushUntil = 0
  private listedAt = -Infinity
  private listTold = false
  private stopNotices: (() => void) | null = null

  constructor(private readonly core: CoreApi, private readonly machineId: string, options: { now?: () => number; intervalMs?: number; reads?: SwarmReads; log?: (line: string) => void } = {}) {
    this.now = options.now ?? Date.now
    this.intervalMs = options.intervalMs ?? 5000
    this.reads = options.reads ?? new SwarmReads(core)
    this.log = options.log ?? (line => console.log(line))
  }

  /** Poll while a capable Pro is attached; none otherwise (no request at all). `include`: the Swarms the desktop has tabs for,
   *  read first. `focus`: the conversation the window has open in a Swarm tab; a change rebuilds the cards at once from the
   *  last reads, with no request. */
  want(on: boolean, include: string[] = [], focus: CardFocus | null = null): void {
    if (!on) {
      if (this.timer) clearInterval(this.timer)
      this.timer = undefined
      this.stopNotices?.()
      this.stopNotices = null
      this.pushUntil = 0
      this.opened.clear(); this.openBy.clear(); this.include = []; this.focus = null
      // A device that attaches again starts a fresh baseline: what was said while none was here never alerts.
      this.seen.clear(); this.forgetNotices()
      return
    }
    const wanted = include.filter(cardId).slice(0, MAX_CARDS)
    const moved = wanted.join(',') !== this.include.join(',')
    this.include = wanted
    const next: CardFocus | null = focus && cardId(focus.tabId) && cardId(focus.conversationId)
      ? { tabId: focus.tabId, conversationId: focus.conversationId } : null
    const refocused = `${next?.tabId}/${next?.conversationId}` !== `${this.focus?.tabId}/${this.focus?.conversationId}`
    this.focus = next
    // Other Swarms to show first: the list is read for them now, whatever the server pushes.
    if (moved) this.listTold = true
    if (this.timer) {
      if (refocused && this.live) { this.emit(); void this.pushOpen() }
      if (moved) void this.tick()
      return
    }
    this.stopNotices = this.core.account.onNotice(notice => this.heard(notice))
    this.timer = setInterval(() => { void this.tick() }, this.intervalMs)
    this.timer.unref?.()
    void this.tick()
  }

  /** The recap on a Pro's screen (leadId null: closed), per Pro `session`: a change in that Lead's conversation is pushed once.
   *  With `chat`, the face chat's: a change in it, or another chat on the face, is pushed once. */
  open(session: string, tabId: string, leadId: string | null, chat: CardChat = false): void {
    const before = this.openBy.get(session)
    if (before) {
      const held = this.opened.get(before)
      held?.sessions.delete(session)
      if (held && !held.sessions.size) this.opened.delete(before)
      this.openBy.delete(session)
    }
    if (!leadId || !cardId(session) || !cardId(tabId) || !cardId(leadId)) return
    const key = `${recapKey(tabId, leadId)}${chat === 'buddy' ? ':buddy' : chat ? ':chat' : ''}`
    let entry = this.opened.get(key)
    if (!entry) {
      // From what the Pro was shown when there is a recap read, else from the first read of the tab: the next change is pushed.
      const target = this.target(tabId, leadId, chat)
      entry = { tabId, leadId, chat, chatId: target?.chatId ?? null,
        sequence: target ? this.recaps.get(cachedKey(tabId, leadId, target, chat))?.sequence ?? target.sequence : null, sessions: new Set() }
      this.opened.set(key, entry)
    }
    entry.sessions.add(session)
    this.openBy.set(session, key)
  }

  /** Whether a Swarm read last lists this harness on that machine as one of its workers (a Builder or Reviewer): a member
   *  that leads no conversation and that the Swarm started, by its start record (the proof superTabs/host.ts closes workers
   *  by). A session the person opened by hand and added is theirs, as on this computer (services/devices.ts). A Swarm
   *  Reviewer on another computer failing every turn took over the round dial (2026-10-28), so the devices ask before they
   *  show a card's failure. Nothing is read for it: before the first poll, nobody is one. A Buddy (`buddyOf`) is started
   *  the same way but is its owner's own agent, so its failures stay on their dial (combination review of batch #2043). */
  worker(machineId: string, harnessId: string): boolean {
    return [...this.tabs.values()].some(({ state }) => {
      const member = list(state.agents).find(a => a.machineId === machineId && a.harnessId === harnessId)
      return !!member && !member.buddyOf && !list(state.conversations).some(c => c.leadId === member.id)
        && list(state.starts).some(s => s.harnessId === harnessId && object(s.request).machineId === machineId && !s.error
          && s.creationId === `super-${String(s.id)}`)
    })
  }

  /** The server's word on this account's Swarms: naming none, it pushes them (and what changed meanwhile is read once); naming
   *  one, a change to its main parts is read at the next tick. A machine's reading alone changes nothing a card shows. */
  private heard(notice: BackendNotice): void {
    if (notice.type !== 'swarm_changed') return
    if (notice.tabId === undefined && notice.parts === undefined) {
      this.pushUntil = this.now() + SWARM_PUSH_LEASE_MS
      this.listTold = true
    } else if (notice.parts?.includes('main')) this.listTold = true
  }

  async tick(): Promise<void> {
    if (this.busy) return
    this.busy = true
    try { await this.poll() } catch { /* the last cards stay: a dropped network says nothing about the Swarms */ } finally { this.busy = false }
  }

  /** The Swarms to show: those the desktop has tabs for first, then the list in its order, 16 in all. Paging stops once both are met. */
  private async listTabs(): Promise<Json[]> {
    const rows: Json[] = []
    let after = ''
    for (let page = 0; page < MAX_LIST_PAGES; page++) {
      const data = object(await backend(this.core, 'GET', `/api/super-tabs/list${after ? `?after=${encodeURIComponent(after)}` : ''}`))
      rows.push(...list(data.tabs).filter(r => cardId(r.id)))
      if (!identifier(data.next)) break
      if (rows.length >= MAX_CARDS && this.include.every(id => rows.some(r => r.id === id))) break
      after = data.next
    }
    const first = this.include.map(id => rows.find(r => r.id === id)).filter((r): r is Json => !!r)
    return [...first, ...rows.filter(r => !first.includes(r))].slice(0, MAX_CARDS)
  }

  private async poll(): Promise<void> {
    // The list and the Swarms it says changed, unless the server pushes and nothing it said asks for them: the rest of the
    // poll (the turns here, the Leads' new messages, the cards) still runs each tick from the last reads.
    if (this.now() >= this.pushUntil || this.listTold || this.now() - this.listedAt >= CARDS_SAFETY_MS) {
      // Cleared before the read: a change told during it asks for another.
      this.listTold = false
      let rows: Json[]
      try { rows = await this.listTabs() } catch (error) { this.listTold = true; throw error }
      this.listedAt = this.now()
      const known = new Map<string, TabCache>()
      let unread = false
      await Promise.all(rows.map(async row => {
        const id = row.id as string, held = this.tabs.get(id)
        // A row without a numeric change time cannot say it is unchanged: that tab is always read again.
        if (held && typeof row.lastChangedAt === 'number' && held.lastChangedAt === row.lastChangedAt) { known.set(id, held); return }
        try { known.set(id, tabOf(await this.reads.read(id))) } catch (error) {
          // Lost access drops only this card; any other failure keeps what was read before.
          const status = error instanceof SuperTabHostError ? error.status : 0
          if (status === 401 || status === 403) return
          if (held) known.set(id, held)
          else unread = true
        }
      }))
      this.tabs = known
      // A Swarm that could not be read and is not held is read again next tick, push or not.
      if (unread) this.listTold = true
      // After a restart nothing is held, so one passing failure (a 5xx, a timeout) would leave that Swarm out of the first list,
      // and the dial takes a list without a Swarm to mean it went. Bounded: a Swarm that keeps failing must not hide the others.
      const first = unread && this.last === null
      this.unreadSince = first ? this.unreadSince ?? this.now() : null
      this.holding = this.unreadSince !== null && this.now() - this.unreadSince < UNREAD_HOLD_MS
      this.rows = rows.map(row => ({ id: row.id as string, name: row.name }))
      this.personal = new Set(rows.filter(row => row.personal === true).map(row => row.id as string))
    }
    const me = (await this.core.account.identity().catch(() => null))?.accountId
    // Another person signed in: nothing of the last account's is kept, and the list is said again whatever it is.
    if (this.me !== undefined && me !== this.me) { this.last = null; this.recaps.clear(); this.seen.clear(); this.forgetNotices() }
    this.me = me ?? this.me
    const turns = await this.turnsHere()
    this.live = (harnessId: string) => this.core.agents.byAgent(harnessId) ? turns.get(harnessId) ?? { inTurn: false } : null
    await this.watchNotices()
    this.emit()
    this.prune()
    await this.pushOpen()
  }

  /** The cards from the last reads, said when they changed. */
  private emit(): void {
    if (this.holding) return
    const live = this.live ?? (() => null)
    const cards: SwarmCard[] = []
    for (const row of this.rows) {
      const tab = this.tabs.get(row.id)
      if (!tab) continue
      const focus = this.focus?.tabId === row.id ? this.focus.conversationId : undefined
      const { count, leads } = leadsOf(tab.state, this.machineId, live, this.me, focus)
      const noticed = leads.map(lead => {
        const notice = this.notices.get(recapKey(row.id, lead.id)), buddyNotice = this.buddyNotices.get(recapKey(row.id, lead.id))
        return { ...lead, ...(notice ? { notice } : {}), ...(buddyNotice ? { buddyNotice } : {}) }
      })
      cards.push({ id: row.id, name: cut(String(tab.state.name ?? row.name ?? ''), NAME_BYTES), count, leads: noticed,
        ...(this.personal.has(row.id) ? { personal: true as const } : {}) })
    }
    // `since` moves every poll while a turn runs and the Pro counts on by itself, so it alone never re-sends the list.
    // Nor does a clock that keeps its turn; one whose turn changed (the Lead's ended, a worker's goes on) does. The start is
    // compared within 2 s: `since` is whole seconds, read at a poll's own moment.
    const signature = JSON.stringify(cards, (key, value) => key === 'since' ? value !== undefined : value)
    const now = this.now(), starts = new Map<string, number>()
    for (const card of cards) for (const lead of card.leads) if (lead.since !== undefined) starts.set(`${card.id}/${lead.id}`, now - lead.since * 1000)
    const moved = [...starts].some(([key, at]) => Math.abs(at - (this.lastStarts.get(key) ?? at)) > 2000)
    if (signature !== this.last || moved) { this.last = signature; this.lastStarts = starts; this.onCards?.(cards) }
  }

  /**
   * The dial's alerts (design 2026-10-28 §2, task #2965): each project's Lead holds the newest tag of the reader's in that project
   * (watchTags), and while Buddies are on the reader's Buddy chat gives the newest message of the reader's Buddy as the Lead's
   * quiet notice (spec 2026-10-29 Alerts), kept apart from its notice. A Buddy chat first seen sets the baseline and is not
   * read; one that moved past it, by the `lastMessageSequence` the tab reads already carry, has its newest page read once,
   * under the recaps' limit. The baseline moves only after a read that worked, so a failed one is tried again at the next
   * poll. The PM's own messages are no alert, in its Lead conversation or the reader's Buddy chat: they beeped all day for
   * chatter in projects that had nothing to do with the reader (Diego, 2026-11-04). Another person's Buddy chat is never read.
   */
  private async watchNotices(): Promise<void> {
    const watched = new Set<string>()
    for (const [tabId, { state }] of this.tabs) {
      const conversations = list(state.conversations), agents = list(state.agents), buddies = state.buddies === true
      const projects = leadProjects(state)
      // The reader's one Swarm Buddy chat is every project's Buddy: read once per poll (its key is the chat's), and its newest
      // word is the quiet notice of each Lead alike. A project's own Buddy chat (older Swarms) is that project's alone.
      const swarmChat = buddies ? conversations.find(c => isSwarmBuddyChat(c) && isReadersBuddyChat(c, this.me) && c.archived !== true && cardId(c.id)) : undefined
      const chats: Array<{ conversation: Json; leadIds: string[] }> = [...swarmChat ? [{ conversation: swarmChat, leadIds: projects.map(p => p.leadId) }] : [],
        ...buddies ? projects.flatMap(({ project, leadId }) => conversations.filter(c => !isSwarmBuddyChat(c) && inProject(c, projectKey(project))
          && isReadersBuddyChat(c, this.me) && c.archived !== true && cardId(c.id)).map(conversation => ({ conversation, leadIds: [leadId] }))) : []]
      for (const { conversation, leadIds } of chats) {
        if (typeof conversation.lastMessageSequence !== 'number') continue
        const key = `${tabId}:${conversation.id}`, sequence = conversation.lastMessageSequence, baseline = this.seen.get(key)
        watched.add(key)
        if (baseline === undefined) { this.seen.set(key, sequence); continue }
        if (sequence <= baseline || this.recapsRunning >= MAX_RECAPS_IN_FLIGHT) continue
        this.recapsRunning++
        try {
          const page = object(await backend(this.core, 'GET', `/api/super-tabs/${tabId}/conversations/${conversation.id}/messages`))
          const after = list(page.messages).filter(m => typeof m.sequence === 'number' && m.sequence > baseline)
          const voices = new Set(buddiesIn(agents, conversation, this.me).map(a => a.id as string))
          for (const leadId of leadIds) this.raise(this.buddyNotices, recapKey(tabId, leadId), 'buddy', conversation.id as string, after, voices)
          this.seen.set(key, sequence)
          this.failed.delete(key)
        } catch (error) {
          if (!this.failed.has(key)) {
            this.failed.add(key)
            this.log(`[super-tabs] the Buddy's new message could not be read for the dial; tried again at the next poll: ${error instanceof Error ? error.message : String(error)}`)
          }
        } finally { this.recapsRunning-- }
      }
      watched.add(`${tabId}:mentions`)
      await this.watchTags(tabId, state, projects)
      watched.add(`${tabId}:decisions`)
      await this.watchDecisions(tabId, state, projects)
    }
    // A Swarm or project that left the cards takes its baseline and notices with it.
    for (const key of [...this.seen.keys()]) if (!watched.has(key)) this.seen.delete(key)
    for (const key of [...this.failed]) if (!watched.has(key)) this.failed.delete(key)
    for (const [key, notice] of this.buddyNotices) if (!watched.has(`${key.slice(0, key.indexOf(':'))}:${notice.chatId}`)) this.buddyNotices.delete(key)
    for (const tabId of [...this.tagDigests.keys()]) if (!this.tabs.has(tabId)) { this.tagDigests.delete(tabId); this.tagsSeen.delete(tabId); this.decisionDigests.delete(tabId); this.decisionsSeen.delete(tabId) }
    for (const key of [...this.notices.keys()]) {
      const [tabId, leadId] = key.split(':'), state = this.tabs.get(tabId)?.state
      if (!state || !leadProjects(state).some(p => p.leadId === leadId)) this.notices.delete(key)
    }
  }

  /**
   * The reader's waiting tags in a Swarm, read only when its mentions digest (each Swarm read's `mentionsDigest`) moved, never
   * on a timer. The first digest seen is the baseline: the tags waiting then were there before the dial came, and never alert;
   * at the digest of none there is nothing to read. After it, a tag id not seen before is new, and the newest new tag of a
   * project is its Lead's notice, naming the tag's chat and, for a thread reply, its thread. A tag seen once is never new again;
   * one read or marked done stops waiting, so it never comes back, and the Lead's notice for it goes. A Swarm read from a
   * backend without the digest raises none. A failed read keeps the digest, so the next poll reads again.
   */
  private async watchTags(tabId: string, state: Json, projects: Array<{ project: Json; lead: Json; leadId: string }>): Promise<void> {
    const digest = state.mentionsDigest, seen = this.tagsSeen.get(tabId)
    if (typeof digest !== 'string' || this.tagDigests.get(tabId) === digest) return
    if (seen === undefined && digest === NO_TAGS) { this.tagDigests.set(tabId, digest); this.tagsSeen.set(tabId, []); return }
    if (this.recapsRunning >= MAX_RECAPS_IN_FLIGHT) return
    const key = `${tabId}:mentions`
    this.recapsRunning++
    try {
      const rows = list(object(await backend(this.core, 'GET', `/api/super-tabs/${tabId}/mentions?state=waiting`)).mentions).filter(r => cardId(r.id))
      const waiting = new Set(rows.map(r => r.id as string))
      if (seen) {
        const known = new Set(seen)
        this.raiseTags(tabId, state, projects, rows.filter(r => !known.has(r.id as string)))
      }
      // A decision's notice is dropped by watchDecisions, not here; the tag under it goes with the tag.
      for (const { leadId } of projects) {
        const held = this.notices.get(recapKey(tabId, leadId))
        if (held?.decision) { if (held.tag && !waiting.has(held.tag.id)) delete held.tag }
        else if (held && !waiting.has(held.id)) this.notices.delete(recapKey(tabId, leadId))
      }
      this.tagsSeen.set(tabId, [...(seen ?? []).filter(id => !waiting.has(id)), ...waiting].slice(-MAX_TAGS_SEEN))
      this.tagDigests.set(tabId, digest)
      this.failed.delete(key)
    } catch (error) {
      if (!this.failed.has(key)) {
        this.failed.add(key)
        this.log(`[super-tabs] the tags waiting for you could not be read for the dial; tried again at the next poll: ${error instanceof Error ? error.message : String(error)}`)
      }
    } finally { this.recapsRunning-- }
  }

  /**
   * The decisions asked of the reader, as the tags are (spec 2026-11-05-dial-lead-pm-buddy-pair, Notices): read only when the
   * Swarm read's `decisionsDigest` moved. The server lists the reader's own open ones (`/decisions?state=open`; for a person
   * it is never another's); the first digest seen is the baseline and never alerts, a decision id seen once is never new
   * again, and the newest new one of a project is its Lead's notice, "<asker> asks you: <question>". The newest of a tag or a
   * decision wins. One no longer open drops the notice it made. A failed read keeps the digest, so the next poll reads again.
   */
  private async watchDecisions(tabId: string, state: Json, projects: Array<{ project: Json; lead: Json; leadId: string }>): Promise<void> {
    const digest = state.decisionsDigest, seen = this.decisionsSeen.get(tabId)
    if (typeof digest !== 'string' || this.decisionDigests.get(tabId) === digest) return
    if (this.recapsRunning >= MAX_RECAPS_IN_FLIGHT) return
    const key = `${tabId}:decisions`
    this.recapsRunning++
    try {
      const page = object(await backend(this.core, 'GET', `/api/super-tabs/${tabId}/decisions?state=open`))
      // One page: with `more`, a decision missing from it may be open still, so none is taken as closed.
      const more = page.more === true
      const rows = list(page.decisions).filter(r => cardId(r.id) && (r.answeredAt === null || r.answeredAt === undefined))
      const open = new Set(rows.map(r => r.id as string))
      if (seen) {
        const known = new Set(seen)
        for (const row of rows.filter(r => !known.has(r.id as string))) {
          const found = projects.find(p => projectKey(p.project) === row.projectId)
          if (!found || !cardId(row.conversationId) || typeof row.question !== 'string') continue
          const stamp = Date.parse(String(row.createdAt))
          const asker = typeof row.askerName === 'string' && row.askerName ? row.askerName : 'Agent'
          const notice: LeadNotice = { chat: noticeChat(state, row.conversationId, found.lead.id), chatId: row.conversationId, id: row.id as string,
            text: cut(`${asker} asks you: ${row.question}`, RECAP_BYTES), at: Number.isFinite(stamp) ? Math.floor(stamp / 1000) : 0, decision: true }
          const held = this.notices.get(recapKey(tabId, found.leadId))
          if (held && held.at > notice.at) continue
          // The tag it covers stays under it, for a dial that hears no decisions.
          const tagBelow = held?.decision ? held.tag : held
          this.notices.set(recapKey(tabId, found.leadId), tagBelow ? { ...notice, tag: tagBelow } : notice)
        }
      }
      // A notice made by a decision that is no longer open goes (a tag's own is dropped by watchTags).
      for (const { leadId } of projects) {
        const held = this.notices.get(recapKey(tabId, leadId))
        if (!more && held?.decision && !open.has(held.id)) {
          if (held.tag) this.notices.set(recapKey(tabId, leadId), held.tag)
          else this.notices.delete(recapKey(tabId, leadId))
        }
      }
      this.decisionsSeen.set(tabId, [...(seen ?? []).filter(id => !open.has(id)), ...open].slice(-MAX_TAGS_SEEN))
      this.decisionDigests.set(tabId, digest)
      this.failed.delete(key)
    } catch (error) {
      if (!this.failed.has(key)) {
        this.failed.add(key)
        this.log(`[super-tabs] the decisions asked of you could not be read for the dial; tried again at the next poll: ${error instanceof Error ? error.message : String(error)}`)
      }
    } finally { this.recapsRunning-- }
  }

  /** New tags (`rows`, as `/mentions` lists them) as their project Lead's notice: the newest of each project, unless the one
   *  held is newer. Its chat is `lead` in the project's Lead conversation, `pm` in the reader's Buddy chat or a Chat with PM,
   *  and `group` elsewhere (a task chat); its text names who tagged. A tag of a project with no Lead makes none. */
  private raiseTags(tabId: string, state: Json, projects: Array<{ project: Json; lead: Json; leadId: string }>, rows: Json[]): void {
    for (const row of rows) {
      const found = projects.find(p => projectKey(p.project) === row.projectId)
      if (!found || !cardId(row.conversationId) || typeof row.text !== 'string') continue
      const chat = noticeChat(state, row.conversationId, found.lead.id)
      const stamp = Date.parse(String(row.createdAt))
      const at = Number.isFinite(stamp) ? Math.floor(stamp / 1000) : 0
      const who = typeof row.leadName === 'string' && row.leadName ? `${row.leadName}: ` : ''
      const notice: LeadNotice = { chat, chatId: row.conversationId, id: row.id as string, text: cut(`${who}${row.text}`, RECAP_BYTES), at,
        ...(identifier(row.threadId) ? { thread: row.threadId } : {}) }
      const held = this.notices.get(recapKey(tabId, found.leadId))
      if (held && held.at > notice.at) { if (held.decision && (!held.tag || held.tag.at <= notice.at)) held.tag = notice; continue }
      this.notices.set(recapKey(tabId, found.leadId), notice)
    }
  }

  /** The newest message `voices` said in `messages` becomes the held notice at `key`, unless one held is newer; with its
   *  thread when it replies in one only. Since tasks live in threads (#2704) agents answer there, and a notice that read
   *  as its chat's was read by opening the chat while the reply sat collapsed in its thread (Diego, 2026-10-29). */
  private raise(held: Map<string, LeadNotice>, key: string, chat: LeadNotice['chat'], chatId: string, messages: Json[], voices: ReadonlySet<string>): void {
    const said = lastAgentMessage(messages, voices)
    if (!said || !cardId(said.id)) return
    const notice: LeadNotice = { chat, chatId, id: said.id, text: cut(said.text, RECAP_BYTES), at: said.at, ...(said.thread ? { thread: said.thread } : {}) }
    const before = held.get(key)
    if (before && before.at > notice.at) return
    held.set(key, notice)
  }

  private forgetNotices(): void { this.notices.clear(); this.buddyNotices.clear(); this.tagDigests.clear(); this.tagsSeen.clear(); this.decisionDigests.clear(); this.decisionsSeen.clear(); this.failed.clear() }

  /** Which of the Leads that run here are in a turn, and since when (the core's windows' own measure of "working"). */
  private async turnsHere(): Promise<Map<string, { inTurn: boolean; since?: number }>> {
    const ids = new Set<string>()
    for (const { state } of this.tabs.values()) {
      for (const agent of list(state.agents)) if (agent.machineId === this.machineId && typeof agent.harnessId === 'string' && this.core.agents.byAgent(agent.harnessId)) ids.add(agent.harnessId)
    }
    const working = ids.size ? await this.core.agents.activity([...ids]).catch(() => ({} as Record<string, string>)) : {}
    const out = new Map<string, { inTurn: boolean; since?: number }>()
    const now = this.now()
    for (const id of ids) {
      if (working[id] !== 'working') { this.turns.delete(id); out.set(id, { inTurn: false }); continue }
      if (!this.turns.has(id)) {
        const elapsed = (await this.core.agents.activitySnapshot?.(id).catch(() => null))?.elapsedSeconds
        this.turns.set(id, now - (typeof elapsed === 'number' && elapsed > 0 ? elapsed * 1000 : 0))
      }
      // At least 1: the Pro reads 0 as no turn start and shows no clock.
      out.set(id, { inTurn: true, since: Math.max(1, Math.floor((now - this.turns.get(id)!) / 1000)) })
    }
    for (const id of [...this.turns.keys()]) if (!ids.has(id)) this.turns.delete(id)
    return out
  }

  /** Where the Lead's recap is read and its talk posted, from the tab as last read: its Lead conversation, or with `chat` the
   *  chat on its project's face for that dial (`chatId` set): today's, or with 'buddy' the side a swarmBuddy dial keeps
   *  while the Swarm has Buddies on. */
  private target(tabId: string, leadId: string, chat: CardChat): Target | null {
    const state = this.tabs.get(tabId)?.state
    if (!state) return null
    const found = leadProjects(state).find(p => p.leadId === leadId)
    if (!found || !identifier(found.lead.id)) return null
    if (!chat) return { id: found.lead.id, sequence: sequenceOf(found.lead), voices: new Set([leadId]) }
    const focus = this.focus?.tabId === tabId ? this.focus.conversationId : undefined
    const conversations = list(state.conversations), projectId = projectKey(found.project), buddies = state.buddies === true
    const face = chat === 'buddy' && buddies ? buddyFaceOf(conversations, projectId, this.me)
      : faceOf(conversations, projectId, found.lead, focus, this.me, buddies)
    if (!face) return null
    const id = face.conversation.id as string
    return { id, sequence: sequenceOf(face.conversation), voices: voicesOf(face, leadId, list(state.agents), this.me), chatId: id,
      ...(face.kind === 'buddy' ? { buddy: true as const } : {}) }
  }

  /** What the Lead last said: the newest page of its conversation, then one page back; `none` when neither holds a row of its own.
   *  With `chat`, what the chat on its face last heard from its agents, naming that chat. The dial's own read: never refused,
   *  and answered at once from the recap held for that chat or the Buddy's notice from it, read again after when the chat moved on. */
  async recap(tabId: string, leadId: string, chat: CardChat = false): Promise<LeadRecap> {
    if (!cardId(tabId) || !cardId(leadId)) return { tabId, leadId, text: '', at: 0, none: true }
    const quick = this.held(tabId, leadId, chat)
    if (quick) {
      if (quick.stale) this.refresh(tabId, leadId, chat, quick.recap)
      return quick.recap
    }
    return this.asked(() => this.read(tabId, leadId, chat, 'device'))
  }

  /** The dial's reads, one after another; one asked while none runs starts at once, and one never waits on a read that
   *  hangs for longer than ASK_WAIT_MS. */
  private asked<T>(read: () => Promise<T>): Promise<T> {
    const run = this.asking ? within(this.asking, ASK_WAIT_MS).then(read) : read()
    const done: Promise<unknown> = run.catch(() => {}).then(() => { if (this.asking === done) this.asking = null })
    this.asking = done
    return run
  }

  /** What can be answered for the chat on the face with no read: the recap held for it, or on a Buddy face the newer quiet
   *  notice from it, with the sequence it was read at (-1 for a notice); `stale` when the chat has moved on since, so it is
   *  read again. A tag is not the chat's recap: whoever tagged may be no voice of it. */
  private held(tabId: string, leadId: string, chat: CardChat): { recap: LeadRecap; sequence: number; stale: boolean } | null {
    const found = this.target(tabId, leadId, chat)
    if (!found) return null
    const kept = this.recaps.get(cachedKey(tabId, leadId, found, chat))
    const notice = found.buddy ? this.buddyNotices.get(recapKey(tabId, leadId)) : undefined
    const heard = notice && notice.chatId === found.id && notice.thread === undefined ? notice : undefined
    if (kept && (!heard || heard.at <= kept.recap.at)) return { recap: kept.recap, sequence: kept.sequence, stale: kept.sequence !== found.sequence }
    if (!heard) return null
    return { recap: { tabId, leadId, text: heard.text, at: heard.at, none: false, ...namedFor(found, chat) }, sequence: -1, stale: true }
  }

  /** The chat moved on since what the dial was answered: read again, on the dial's lane, and pushed when it says otherwise. */
  private refresh(tabId: string, leadId: string, chat: CardChat, shown: LeadRecap): void {
    void this.asked(() => this.read(tabId, leadId, chat, 'device')).then(recap => {
      // Its open sessions are told this one: their next push is for the chat's next move.
      const target = this.target(tabId, leadId, chat), kept = target && this.recaps.get(cachedKey(tabId, leadId, target, chat))
      for (const open of this.opened.values()) {
        if (kept && open.tabId === tabId && open.leadId === leadId && open.chat === chat && open.chatId === (target.chatId ?? null)) open.sequence = kept.sequence
      }
      if (recap.text !== shown.text || recap.at !== shown.at || recap.none !== shown.none || recap.chatId !== shown.chatId) this.onRecap?.(recap)
    }, () => { /* read again at the next push or ask */ })
  }

  /** The backend read of a recap. `background` (a push) takes one of the two background slots or is refused; `device` (the
   *  dial asked) runs on the dial's own lane. */
  private async read(tabId: string, leadId: string, chat: CardChat, lane: 'device' | 'background'): Promise<LeadRecap> {
    // At most two background reads run at once, so a loop of pushes cannot flood the backend; the dial's run one by one.
    const slot = async <T>(run: () => Promise<T>): Promise<T> => {
      if (lane === 'device') return run()
      if (this.recapsRunning >= MAX_RECAPS_IN_FLIGHT) throw new Error('too many recap reads at once')
      this.recapsRunning++
      try { return await run() } finally { this.recapsRunning-- }
    }
    let found = this.target(tabId, leadId, chat)
    if (!found) {
      await slot(async () => { this.tabs.set(tabId, tabOf(await this.reads.read(tabId))) })
      found = this.target(tabId, leadId, chat)
    }
    if (!found) return { tabId, leadId, text: '', at: 0, none: true }
    const target = found, named = namedFor(target, chat)
    const key = cachedKey(tabId, leadId, target, chat), held = this.recaps.get(key)
    if (held && held.sequence === target.sequence) return held.recap
    const reader = this.me
    return slot(async () => {
      const path = `/api/super-tabs/${tabId}/conversations/${target.id}/messages`
      const newest = object(await backend(this.core, 'GET', path))
      let said = lastAgentMessage(list(newest.messages), target.voices, 'chat')
      // The page before, from the page's own (sequence, id) cursor: a page edge inside equal sequences skips nothing (design 4.6).
      const before = object(newest.next)
      if (!said && typeof before.sequence === 'number' && identifier(before.id)) {
        said = lastAgentMessage(list(object(await backend(this.core, 'GET', `${path}?before=${before.sequence}&beforeId=${before.id}`)).messages), target.voices, 'chat')
      }
      // Access to the Swarm ended, another person signed in, or the face moved on while the read was out: the answer is not
      // this reader's to have now (a Buddy chat is its owner's alone), so it is neither given nor kept.
      const now = this.target(tabId, leadId, chat)
      if (this.me !== reader || now?.id !== target.id) return { tabId, leadId, text: '', at: 0, none: true }
      const recap: LeadRecap = said ? { tabId, leadId, text: cut(said.text, RECAP_BYTES), at: said.at, none: false, ...named } : { tabId, leadId, text: '', at: 0, none: true, ...named }
      this.recaps.set(key, { sequence: target.sequence, recap })
      return recap
    })
  }

  /** Words spoken on a Pro to a Lead that runs here (its harness): posted as the person in that Lead's conversation, as typed in
   *  the Swarm chat; with `chat`, in the chat on its face. Not `said` when that harness leads no project in the Swarms as last
   *  read, so the caller sends the turn as before; `refused` when the backend refused the post (a 4xx: a read-only Chat with
   *  PM, Buddies off, a Buddy chat not the reader's), whose words must never become a terminal turn instead (spec 2026-10-29
   *  Voice). Any other failure (the network, a 5xx) throws as before. `chatId`: the chat on the dial's face when the words
   *  were spoken; they go there or nowhere, so words for the reader's Buddy never land in the project's chat because the
   *  window moved on while they were said (review of #2146). `reviewed`: the person saw that chat named and pressed Send,
   *  so the words go there even if the face moved since, while it is still a chat of the Lead's project this reader may
   *  see (docs/device-voice-swarm-chat.md); the backend checks the post as for typing. `options.thread`: the thread on the
   *  face when the words were spoken (null: none), pinned like `chatId`: another one now refuses the words (CHAT_MOVED), unless
   *  `reviewed`, which posts them where they were spoken. `options.threaded`: the words came from the face, so a top-level post
   *  may start the dial's thread, if nothing moved meanwhile (spec 2026-11-03-dial-thread-face). */
  async say(harnessId: string, text: string, chat: CardChat = false, chatId?: string, reviewed = false): Promise<SaidOnCard> {
    for (const [tabId, { state }] of this.tabs) {
      // A Lead on another machine has no harness here, so the dial names it by its Swarm id (Diego's dial, 2026-10-29).
      const agent = list(state.agents).find(a => (a.machineId === this.machineId && a.harnessId === harnessId) || a.id === harnessId)
      const found = agent && cardId(agent.id) ? this.target(tabId, agent.id, chat) : null
      if (!found) continue
      const to = chatId === undefined || found.id === chatId ? found.id
        : reviewed && this.chatOfLead(state, agent!.id as string, chatId) ? chatId : null
      if (!to) return { said: false, refused: { code: 'CHAT_MOVED', message: 'That chat is no longer on the dial. Say it again.' } }
      let sent: unknown
      try {
        sent = await backend(this.core, 'POST', `/api/super-tabs/${tabId}/commands`, { operationId: `pro-voice-${randomUUID()}`,
          command: { type: 'message.send', conversationId: to, text, replyTo: null, recipientIds: [] } })
      } catch (error) {
        if (error instanceof SuperTabHostError && error.status >= 400 && error.status < 500) return { said: false, refused: { code: error.code, message: error.message } }
        throw error
      }
      return { said: true }
    }
    return { said: false }
  }

  /** Whether `chatId` is, as last read, a chat that could be on this Lead's face: its Lead conversation, or an open chat of its
   *  project that is not another person's Buddy chat. */
  private chatOfLead(state: Json, leadId: string, chatId: string): boolean {
    const found = leadProjects(state).find(p => p.leadId === leadId)
    if (!found) return false
    if (found.lead.id === chatId) return true
    const c = list(state.conversations).find(c => c.id === chatId)
    return !!c && cardId(c.id) && c.archived !== true && (isSwarmBuddyChat(c) ? isReadersBuddyChat(c, this.me)
      : inProject(c, projectKey(found.project)) && (!isBuddyChat(c) || isReadersBuddyChat(c, this.me)))
  }

  /** Remembered recaps are kept only for Leads that are still in a tab, and a chat's only while it could be on the Lead's
   *  face: a swipe back to the other side, or the window back on a chat, is answered from it at once. */
  private prune(): void {
    for (const [key, held] of this.recaps) {
      const { tabId, leadId, chatId } = held.recap
      const state = this.tabs.get(tabId)?.state
      if (!state || !leadProjects(state).some(p => p.leadId === leadId) || (chatId !== undefined && !this.chatOfLead(state, leadId, chatId))) this.recaps.delete(key)
    }
  }

  /** Each open Lead that moved on since its Pro last got the recap, or whose face shows another chat: the new one is sent once.
   *  A failed read is tried again next tick. */
  private pushOpen(): Promise<void> {
    const run = this.pushing.then(() => this.pushOpenNow())
    this.pushing = run.catch(() => {})
    return run
  }
  private async pushOpenNow(): Promise<void> {
    for (const open of [...this.opened.values()]) {
      const target = this.target(open.tabId, open.leadId, open.chat)
      if (!target) continue
      if (open.sequence === null) { open.sequence = target.sequence; open.chatId = target.chatId ?? null; continue }
      if (open.sequence === target.sequence && open.chatId === (target.chatId ?? null)) continue
      // Another chat on the face (a swipe, the window's move): what is held for it is pushed at once, and read again after.
      const moved = open.chatId !== (target.chatId ?? null)
      const quick = moved ? this.held(open.tabId, open.leadId, open.chat) : null
      const recap = quick?.recap ?? await this.read(open.tabId, open.leadId, open.chat, 'background').catch(() => null)
      if (!recap) continue
      open.sequence = quick ? quick.sequence : target.sequence
      open.chatId = target.chatId ?? null
      this.onRecap?.(recap)
      if (quick?.stale) this.refresh(open.tabId, open.leadId, open.chat, recap)
    }
  }
}

/** How a chat's recap names it: by its id, and as a swarmBuddy dial's when asked for one. */
function namedFor(target: Target, chat: CardChat): { chatId?: string; buddy?: true } {
  return target.chatId === undefined ? {} : { chatId: target.chatId, ...(chat === 'buddy' ? { buddy: true as const } : {}) }
}


/** Each project of a tab whose Lead conversation names its Lead: the project, that conversation and the Lead agent's id. */
function leadProjects(state: Json): Array<{ project: Json; lead: Json; leadId: string }> {
  const conversations = list(state.conversations)
  const projects = Array.isArray(state.projects) ? list(state.projects) : [{ id: 'lead', leadConversationId: 'lead' }]
  const out: Array<{ project: Json; lead: Json; leadId: string }> = []
  for (const project of projects) {
    const lead = conversations.find(c => c.id === project.leadConversationId)
    if (lead && typeof lead.leadId === 'string') out.push({ project, lead, leadId: lead.leadId })
  }
  return out
}