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.

Merge batch 11-04 b0907: #2810 (#2880)

0xken151940c2c5d606
diff --git a/cli/src/cable/cableSession.spec.ts b/cli/src/cable/cableSession.spec.ts
index 975fc4173..4c70c5848 100644
--- a/cli/src/cable/cableSession.spec.ts
+++ b/cli/src/cable/cableSession.spec.ts
@@ -3944,7 +3944,7 @@ describe('swarm cards', () => {
swarms: rows.map((r) => ({ name: r.id, agents: 0, agentIds: [] as string[], panes: 0, ...r })) })
/** A host whose cards, desk tab and window project the test moves. */
- function cardHost(state: { cards: SwarmCard[] | null; desk?: ReturnType<typeof desk>; open?: { superTabId: string; projectId: string; conversationId?: string; fromDevice: boolean } | null } , over: Partial<CableHost> = {}) {
+ function cardHost(state: { cards: SwarmCard[] | null; desk?: ReturnType<typeof desk>; open?: { superTabId: string; projectId: string; conversationId?: string; threadRoot?: string; fromDevice: boolean } | null } , over: Partial<CableHost> = {}) {
return makeHost({
swarmCards: () => state.cards,
listSwarms: () => state.desk ?? desk(),
@@ -5375,6 +5375,56 @@ describe('swarm cards', () => {
const threaded = () => withBuddy({ local: 'h1', sideChat: inThread, chat: { ...pmChat, thread: { root: 'm9', title: 'build it' } } })
const threadKeys = (l: Record<string, unknown>) => Object.fromEntries(Object.entries(l).filter(([k]) => k.startsWith('thread')))
+ // A PM reply inside a task thread (Diego, 2026-10-29): opening its chat is not reading it.
+ const pmFrame = { t: 'supertab.notice', tab: 'st1', lead: 'lead1', chat: 'pm', chatId: 'pm1', id: 'n1', text: 'From the PM n1', at: 1792560000 }
+ it('a thread notice is sent while its chat is open, and read only when the window opens that thread', async () => {
+ const state: Parameters<typeof cardHost>[0] = { cards: [card('st1', [lead(1, { chat: pmChat })])], open: { superTabId: 'st1', projectId: 'proj1', conversationId: 'pm1', fromDevice: false } }
+ const { session, port } = await connect(cardHost(state))
+ try {
+ port.say(ROUND_THREAD)
+ await vi.waitFor(() => expect(ofType(port, 'supertab')).toHaveLength(1))
+ state.cards = [card('st1', [lead(1, { chat: pmChat, notice: { ...pmNotice('n1'), thread: 'r1' } })])]
+ await session.syncSwarmCards()
+ await vi.waitFor(() => expect(ofType(port, 'supertab.notice')).toEqual([{ ...pmFrame, thread: 'r1' }]))
+ // Another thread of that chat open: still unread.
+ state.open = { superTabId: 'st1', projectId: 'proj1', conversationId: 'pm1', threadRoot: 'r2', fromDevice: false }
+ await session.syncSwarmCards()
+ await new Promise((r) => setTimeout(r, 350))
+ expect(ofType(port, 'supertab.notice.read')).toEqual([])
+ state.open = { superTabId: 'st1', projectId: 'proj1', conversationId: 'pm1', threadRoot: 'r1', fromDevice: false }
+ await session.syncSwarmCards()
+ await vi.waitFor(() => expect(ofType(port, 'supertab.notice.read')).toEqual([{ t: 'supertab.notice.read', tab: 'st1', lead: 'lead1', chatId: 'pm1' }]))
+ await session.syncSwarmCards()
+ await new Promise((r) => setTimeout(r, 350))
+ expect(ofType(port, 'supertab.notice.read')).toHaveLength(1)
+ } finally { await session.stop() }
+ })
+
+ it('a thread notice that arrives while the window has that thread open is read there, and not sent', async () => {
+ const state: Parameters<typeof cardHost>[0] = { cards: [card('st1', [lead(1, { chat: pmChat })])], open: { superTabId: 'st1', projectId: 'proj1', conversationId: 'pm1', threadRoot: 'r1', fromDevice: false } }
+ const { session, port } = await connect(cardHost(state))
+ try {
+ port.say(ROUND_THREAD)
+ await vi.waitFor(() => expect(ofType(port, 'supertab')).toHaveLength(1))
+ state.cards = [card('st1', [lead(1, { chat: pmChat, notice: { ...pmNotice('n1'), thread: 'r1' } })])]
+ await session.syncSwarmCards()
+ await new Promise((r) => setTimeout(r, 350))
+ expect(ofType(port, 'supertab.notice')).toEqual([])
+ } finally { await session.stop() }
+ })
+
+ it('a dial without swarmThread gets today\'s frame for a thread notice', async () => {
+ const state: Parameters<typeof cardHost>[0] = { cards: [card('st1', [lead(1, { chat: pmChat })])], open: { superTabId: 'st1', projectId: 'proj1', conversationId: 'pm1', fromDevice: false } }
+ const { session, port } = await connect(cardHost(state))
+ try {
+ port.say(ROUND)
+ await vi.waitFor(() => expect(ofType(port, 'supertab')).toHaveLength(1))
+ state.cards = [card('st1', [lead(1, { chat: pmChat, notice: { ...pmNotice('n1'), thread: 'r1' } })])]
+ await session.syncSwarmCards()
+ await vi.waitFor(() => expect(ofType(port, 'supertab.notice')).toEqual([pmFrame]))
+ } finally { await session.stop() }
+ })
+
it('a swarmThread dial is sent the face\'s thread and its recap\'s thread', async () => {
for (const [hello, expected] of [[THREAD, { thread: 'm9', threadTitle: 'build it', threadReplies: 2 }], [ROUND_THREAD, { thread: 'm9', threadTitle: 'build it' }]] as const) {
const host = cardHost({ cards: [card('st1', [threaded()])] }, {
diff --git a/cli/src/cable/cableSession.ts b/cli/src/cable/cableSession.ts
index 2cd01b1ba..efb305fa0 100644
--- a/cli/src/cable/cableSession.ts
+++ b/cli/src/cable/cableSession.ts
@@ -235,8 +235,10 @@ function fitFrame(frame: { name: string; leads: Array<Record<string, unknown>> }
return { threads, buddies: blocks }
}
/** A Lead's new message as the round dial's alert, sized as the recap is. */
-function noticeFrame(tab: string, lead: string, n: LeadNotice): Message {
- return fitText(n.text, (text) => ({ t: 'supertab.notice', tab, lead, chat: n.chat, chatId: n.chatId, id: n.id, text, at: n.at }))
+/** `threaded`: a swarmThread dial, which is told the thread a reply is in, and reads it only on that thread's face. */
+function noticeFrame(tab: string, lead: string, n: LeadNotice, threaded = false): Message {
+ return fitText(n.text, (text) => ({ t: 'supertab.notice', tab, lead, chat: n.chat, chatId: n.chatId, id: n.id, text, at: n.at,
+ ...(threaded && n.thread ? { thread: n.thread } : {}) }))
}
/** `make(text)`, with the text shortened (on a character) until the whole JSON fits what a dial reads: escapes can grow
* 1,500 bytes of text past it. */
@@ -2843,7 +2845,8 @@ export class CableSession {
private readonly recapsMissed = new Set<string>()
/** A swarmChat dial's alerts (`${tab}:${lead}`): the notice it was last given or shown as already there, and whether it
* was read on the desktop since. A notice is sent once, never on an attach or resync (it was there before), never for
- * the chat the desktop has open; `notice.read` once when the desktop opens the chat of one that was sent. */
+ * the chat the desktop has open (a thread reply: that thread); `notice.read` once when the desktop opens the chat (or the
+ * thread) of one that was sent. */
private readonly notices = new Map<string, { id: string; chatId: string; open: boolean }>()
/** Until this session has seen a list with Swarms in it: the first one is a replay too. A dial can attach before its
* process has the cards (the devices' process started again), and the core's replay of the last list then comes as an
@@ -3025,7 +3028,7 @@ export class CableSession {
if (this.swarmBuddy) notices.push([`${card.id}:${lead.id}:buddy`, lead.buddyNotice])
for (const [key, notice] of notices) {
live.add(key)
- await this.pushNotice(key, card.id, lead.id, notice, replay, open?.superTabId === card.id ? open.conversationId : undefined)
+ await this.pushNotice(key, card.id, lead.id, notice, replay, open?.superTabId === card.id ? open : undefined)
}
}
}
@@ -3049,17 +3052,19 @@ export class CableSession {
}
}
- /** One alert of a Lead (held at `key`): sent once when it is new, unless replayed or read on the desktop (`openChat`, the
- * conversation the window has open in that Swarm); read on the dial once the desktop opens the chat of one it was sent. */
- private async pushNotice(key: string, tab: string, lead: string, notice: LeadNotice | undefined, replay: boolean, openChat: string | undefined): Promise<void> {
+ /** One alert of a Lead (held at `key`): sent once when it is new, unless replayed or read on the desktop (`open`, the
+ * conversation the window has open in that Swarm and the thread beside it); read on the dial once the desktop opens the
+ * chat of one it was sent. A thread reply is read only by opening that thread: the chat shows it collapsed under "1
+ * reply", and the PM's answer in a task thread used to ring nowhere while its chat was open (Diego, 2026-10-29). */
+ private async pushNotice(key: string, tab: string, lead: string, notice: LeadNotice | undefined, replay: boolean, open: { conversationId?: string; threadRoot?: string } | undefined): Promise<void> {
const held = this.notices.get(key)
if (!notice) { this.notices.delete(key); return }
- const opened = openChat !== undefined && openChat === notice.chatId
+ const opened = open?.conversationId !== undefined && open.conversationId === notice.chatId && (notice.thread === undefined || open.threadRoot === notice.thread)
if (held?.id !== notice.id) {
// Replayed or read on the desktop: noted as not open on the dial, so nothing is sent for it now or later.
const sent = !replay && !opened
this.notices.set(key, { id: notice.id, chatId: notice.chatId, open: sent })
- if (sent) await this.send(noticeFrame(tab, lead, notice))
+ if (sent) await this.send(noticeFrame(tab, lead, notice, this.swarmThread))
return
}
if (held.open && opened) {
diff --git a/cli/src/core/api.ts b/cli/src/core/api.ts
index 42b308cc8..3f4cd88d8 100644
--- a/cli/src/core/api.ts
+++ b/cli/src/core/api.ts
@@ -1276,8 +1276,9 @@ export interface SwarmChat { kind: ChatKind; id: string; name: string; working:
* and, when the read gives it, its reply count. Sent only to a dial that speaks swarmThread. */
thread?: { root: string; title: string; replies?: number } }
/** The newest message the project's Lead wrote in its Lead conversation or the reader's Buddy chat since the baseline (the
- * dial's alert), or the reader's Buddy wrote in its chat (`buddy`, the quiet one). */
-export interface LeadNotice { chat: 'lead' | 'pm' | 'buddy'; chatId: string; id: string; text: string; at: number }
+ * dial's alert), or the reader's Buddy wrote in its chat (`buddy`, the quiet one). `thread`: the root of the thread it
+ * replies in, when it is in that thread only; such a notice is read only where that thread is open. */
+export interface LeadNotice { chat: 'lead' | 'pm' | 'buddy'; chatId: string; id: string; text: string; at: number; thread?: string }
/** The reader's own Buddy in a project, for a round dial's Buddy screen: its chat, name and engine, Desktop's pattern for
* its name (`cells`, the 15 half bits; `color`, `#rrggbb`), and `live` false while it is down. */
export interface SwarmBuddy { chatId: string; name: string; engine: string; cells: number; color: string; live: boolean
diff --git a/cli/src/superTabs/cards.spec.ts b/cli/src/superTabs/cards.spec.ts
index 9abf25a9f..f2fdbfd77 100644
--- a/cli/src/superTabs/cards.spec.ts
+++ b/cli/src/superTabs/cards.spec.ts
@@ -818,6 +818,22 @@ describe('SwarmCards notices', () => {
expect(t.webLead()?.notice).toEqual({ chat: 'pm', chatId: 'pm-web', id: 'x2', text: 'p'.repeat(1499), at: saidAt })
})
+ it('a PM reply inside a thread is a thread notice, named by the thread\'s root', async () => {
+ const t = chatSwarm({ 'pm-web': [said(2, 'a1', { thread: 'r1' })] })
+ await t.cards.tick()
+ await t.move(1, 2)
+ expect(t.webLead()?.notice).toEqual({ chat: 'pm', chatId: 'pm-web', id: 'x2', text: 'm2', at: saidAt, thread: 'r1' })
+ })
+
+ it('a thread reply also sent to the chat, or a thread\'s root, is no thread notice', async () => {
+ for (const over of [{ thread: 'r1', alsoInChat: true }, { thread: 'x2' }]) {
+ const t = chatSwarm({ 'pm-web': [said(2, 'a1', over)] })
+ await t.cards.tick()
+ await t.move(1, 2)
+ expect(t.webLead()?.notice).toEqual({ chat: 'pm', chatId: 'pm-web', id: 'x2', text: 'm2', at: saidAt })
+ }
+ })
+
it('never notices a group message, the person\'s message or a system row', async () => {
const t = chatSwarm({
'lead-web': [said(2, 'me', { author: { kind: 'person', id: 'me' } }), said(3, 'a1', { source: { kind: 'system' } }), said(4, 'b1')],
diff --git a/cli/src/superTabs/cards.ts b/cli/src/superTabs/cards.ts
index a10dd85ad..1f4c68e5f 100644
--- a/cli/src/superTabs/cards.ts
+++ b/cli/src/superTabs/cards.ts
@@ -218,9 +218,10 @@ const isIn = (m: Json, place: MessagePlace): boolean => place === 'any' ? true
: m.thread === place.thread
/** 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. */
-export function lastAgentMessage(messages: Json[], agentIds: ReadonlySet<string>, place: MessagePlace = 'any'): { text: string; at: number; id: string; sequence: number } | null {
- let best: { text: string; at: number; id: string; sequence: number } | null = null
+ * 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
@@ -228,7 +229,8 @@ export function lastAgentMessage(messages: Json[], agentIds: ReadonlySet<string>
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 }
+ 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
}
@@ -304,8 +306,6 @@ export class SwarmCards {
private notices = new Map<string, LeadNotice>()
/** 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>()
- /** The notices that are messages of their chat's main stream, not thread replies: only these answer a chat's recap. */
- private inChat = new WeakSet<LeadNotice>()
/** The side a swarmBuddy dial swiped to, per Swarm; cleared by the window's next focus change (the newest wins). */
private sides = new Map<string, CardSide>()
/** The thread the dial's own words started, per Swarm (spec 2026-11-03-dial-thread-face), and the Lead whose face it was
@@ -680,16 +680,16 @@ export class SwarmCards {
}
}
- /** The newest message `voices` said in `messages` becomes the held notice at `key`, unless one held is newer; marked as the
- * chat's own when it is no thread reply. */
+ /** 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) the PM answers 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 }
+ 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)
- if (lastAgentMessage(messages, voices, 'chat')?.id === said.id) this.inChat.add(notice)
}
private forgetNotices(): void { this.notices.clear(); this.buddyNotices.clear(); this.failed.clear() }
@@ -770,7 +770,7 @@ export class SwarmCards {
const kept = this.recaps.get(cachedKey(tabId, leadId, found, chat))
// A notice is of the chat, never of a thread on the face.
const notice = found.thread === undefined ? (found.buddy ? this.buddyNotices : this.notices).get(recapKey(tabId, leadId)) : undefined
- const heard = notice && notice.chatId === found.id && this.inChat.has(notice) ? notice : 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 }
diff --git a/cli/src/superTabs/inCore/cards.spec.ts b/cli/src/superTabs/inCore/cards.spec.ts
index 570f8b8d5..8439e96bf 100644
--- a/cli/src/superTabs/inCore/cards.spec.ts
+++ b/cli/src/superTabs/inCore/cards.spec.ts
@@ -127,6 +127,24 @@ describe('the Swarm cards on the devices', () => {
cards.recap(recap({ chatId: 'bad id' }))
expect(swarmCardRecap).toHaveBeenCalledOnce()
})
+ // A reply inside a thread (#2463): the notice keeps the thread's root, or the desktop and the dial read it as the chat's.
+ it("keeps a notice's thread, a root too long for the dial still a thread's, and drops one that is not a root", () => {
+ const { cards, swarmCards } = setup()
+ const notice = (over: Record<string, unknown> = {}) => ({ chat: 'pm', chatId: 'pm1', id: 'm2', text: 'Fixed.', at: 1792560000, ...over })
+ const sent = (over: Record<string, unknown>) => {
+ cards.cards([card('t1', [lead('l1', { notice: notice(over), buddyNotice: notice({ chat: 'buddy', ...over }) })])])
+ return swarmCards.mock.lastCall![0][0].leads[0]
+ }
+ expect(sent({ thread: 'm1' })).toMatchObject({ notice: notice({ thread: 'm1' }), buddyNotice: { thread: 'm1' } })
+ // Longer than the dial holds: kept, so no face matches it and the dial beeps; cut to a bound so the frame stays small.
+ expect(sent({ thread: 'r'.repeat(60) }).notice.thread).toBe('r'.repeat(60))
+ expect(sent({ thread: 'r'.repeat(300) }).notice.thread).toBe('r'.repeat(128))
+ for (const bad of ['', 5, null]) {
+ const lead = sent({ thread: bad })
+ expect(lead.notice).toEqual(notice())
+ expect(lead.buddyNotice).not.toHaveProperty('thread')
+ }
+ })
// Round dial PM and Buddy screens (spec 2026-10-29): the swarmBuddy dial's fields, checked as the chat and notice are.
it('keeps the Buddy\'s session id on its way to the devices service; an unsound one is dropped and the Buddy kept', () => {
const { cards, swarmCards } = setup()
diff --git a/cli/src/superTabs/inCore/cards.ts b/cli/src/superTabs/inCore/cards.ts
index 47242eed0..ba2d999e0 100644
--- a/cli/src/superTabs/inCore/cards.ts
+++ b/cli/src/superTabs/inCore/cards.ts
@@ -37,6 +37,8 @@ const MAX_CELLS = 0x7fff
const COLOR = /^#[0-9a-f]{6}$/
/** The dial's thread title: the first line, at most 80 bytes (the cards service cuts it; checked again here). */
const THREAD_TITLE_BYTES = 80
+/** A notice's thread root, cut to this: kept when longer than the dial holds, so no face matches it and the dial beeps. */
+const THREAD_ROOT_BYTES = 128
/** The Pro keeps an id in 48 bytes with its NUL. */
const ID = /^[A-Za-z0-9_-]{1,47}$/
const id = (value: unknown): value is string => typeof value === 'string' && ID.test(value)
@@ -70,7 +72,10 @@ function chatIn(value: unknown): SwarmChat | null {
function noticeIn(value: unknown, chats: ReadonlySet<string>): LeadNotice | null {
const notice = object(value)
if (typeof notice.chat !== 'string' || !chats.has(notice.chat) || !id(notice.chatId) || !id(notice.id) || typeof notice.text !== 'string' || !whole(notice.at)) return null
- return { chat: notice.chat as LeadNotice['chat'], chatId: notice.chatId, id: notice.id, text: cut(notice.text, RECAP_BYTES), at: notice.at }
+ // A reply inside a thread names its root (#2463): without it the desktop and the dial read it by opening the chat.
+ const thread = typeof notice.thread === 'string' && notice.thread ? cut(notice.thread, THREAD_ROOT_BYTES) : undefined
+ return { chat: notice.chat as LeadNotice['chat'], chatId: notice.chatId, id: notice.id, text: cut(notice.text, RECAP_BYTES), at: notice.at,
+ ...(thread ? { thread } : {}) }
}
/** The reader's Buddy on a Lead, checked and cut; null when it is not one. */
diff --git a/devices/harness-device/firmware/main/cable_client.c b/devices/harness-device/firmware/main/cable_client.c
index 7ddb510b8..42ada01ce 100644
--- a/devices/harness-device/firmware/main/cable_client.c
+++ b/devices/harness-device/firmware/main/cable_client.c
@@ -1049,7 +1049,10 @@ static void handle_supertab_notice(const cJSON *p)
const cJSON *at = cJSON_GetObjectItemCaseSensitive(p, "at");
const double secs = cJSON_IsNumber(at) && at->valuedouble > 0 ? at->valuedouble : 0;
ht_chat_kind_t kind = !strcmp(chat, "pm") ? HT_CHAT_PM : !strcmp(chat, "buddy") ? HT_CHAT_BUDDY : HT_CHAT_LEAD;
- if (ui_supertab_notice(tab, lead, kind, chat_id, text,
+ // A reply inside a thread names its root (#2463): read on the face only in that thread. A root too long to hold is
+ // passed as it is: no face's root matches it, so it beeps, never read as the main chat's.
+ const char *thread = str_of(p, "thread");
+ if (ui_supertab_notice(tab, lead, kind, chat_id, thread ? thread : "", text,
secs > 4294967295.0 ? 0xFFFFFFFFu : (uint32_t)secs))
audio_notify_done();
}
diff --git a/devices/harness-device/firmware/main/ui/habitat/ui_habitat.c b/devices/harness-device/firmware/main/ui/habitat/ui_habitat.c
index 50b4f1f1f..4a9b0c099 100644
--- a/devices/harness-device/firmware/main/ui/habitat/ui_habitat.c
+++ b/devices/harness-device/firmware/main/ui/habitat/ui_habitat.c
@@ -5468,7 +5468,9 @@ void ui_supertab_focus(const char *tab, const char *lead)
* A LEAD'S NEW MESSAGE (design 2026-10-28-round-dial-swarm-chat §3), in its Lead conversation or Chat with PM: the one
* alert a swarmChat daemon raises. It is that Lead's single entry, news rather than a question, the message as its text
* and the Swarm's name (with " · PM" for Chat with PM) as its grey line. Each notice counts as unread again; it is read at
- * once only when that Lead's face shows that very chat. True when the caller should beep (the coalescing is the audio's).
+ * once only when that Lead's face shows that very chat, and for a reply inside a thread (`thread`, its root) that very
+ * thread: the main chat shows it collapsed under its root, so the PM's answer in a task thread rang nowhere (#2463). True
+ * when the caller should beep (the coalescing is the audio's).
*/
_Static_assert(SWARM_SAID == NOTICES, "a chat for every inbox entry a Lead's message can take");
static int swarm_said_of(const char *lead)
@@ -5476,10 +5478,10 @@ static int swarm_said_of(const char *lead)
for (int i = 0; lead && i < SWARM_SAID; i++) if (!strcmp(sw.said[i].lead, lead)) return i;
return -1;
}
-bool ui_supertab_notice(const char *tab, const char *lead, ht_chat_kind_t chat, const char *chat_id, const char *text, uint32_t at)
+bool ui_supertab_notice(const char *tab, const char *lead, ht_chat_kind_t chat, const char *chat_id, const char *thread, const char *text, uint32_t at)
{
(void)at;
- if (!tab || !lead || !chat_id || !text) return false;
+ if (!tab || !lead || !chat_id || !thread || !text) return false;
display_lock();
const ht_supertab_t *t = ht_supertabs_find(&swarm, tab);
int i = swarm_lead_index(t, lead);
@@ -5507,7 +5509,7 @@ bool ui_supertab_notice(const char *tab, const char *lead, ht_chat_kind_t chat,
if (slot < 0) slot = 0;
COPY(sw.said[slot].lead, l->id); COPY(sw.said[slot].chat, chat_id);
s.notice_sequence++;
- bool face = on_face(l->id) && !strcmp(l->chat_id, chat_id);
+ bool face = on_face(l->id) && !strcmp(l->chat_id, chat_id) && (!thread[0] || !strcmp(l->thread_root, thread));
if (face) notice_read_now(l->id);
else display_wake();
change();
diff --git a/devices/harness-device/firmware/main/ui/ui_screens.h b/devices/harness-device/firmware/main/ui/ui_screens.h
index 0dbae208b..cede0dac2 100644
--- a/devices/harness-device/firmware/main/ui/ui_screens.h
+++ b/devices/harness-device/firmware/main/ui/ui_screens.h
@@ -262,8 +262,9 @@ bool ui_supertab(const ht_supertab_t *in);
void ui_supertab_recap(const char *tab, const char *lead, const char *chat_id, const char *thread, const char *text, uint32_t at, bool none);
void ui_supertab_focus(const char *tab, const char *lead);
// The Lead's new message in its Lead conversation or Chat with PM (`supertab.notice`): that Lead's one inbox entry, read at
-// once when its chat is on the face. True when the caller should beep.
-bool ui_supertab_notice(const char *tab, const char *lead, ht_chat_kind_t chat, const char *chat_id, const char *text, uint32_t at);
+// once when its chat is on the face. `thread`: the root of the thread it replies in, "" for the main stream; such a notice
+// is read at once only when the face shows that thread. True when the caller should beep.
+bool ui_supertab_notice(const char *tab, const char *lead, ht_chat_kind_t chat, const char *chat_id, const char *thread, const char *text, uint32_t at);
// The desktop opened that chat (`supertab.notice.read`): the entry goes.
void ui_supertab_notice_read(const char *tab, const char *lead, const char *chat_id);
// A Super Tab wait from harness `agent_id` (some Lead's `local`). It only sets that Lead's inbox text and face;
diff --git a/devices/harness-device/firmware/test/test_cable_supertab.py b/devices/harness-device/firmware/test/test_cable_supertab.py
index b2cbfad2e..da0f96a98 100644
--- a/devices/harness-device/firmware/test/test_cable_supertab.py
+++ b/devices/harness-device/firmware/test/test_cable_supertab.py
@@ -68,9 +68,10 @@ static void ui_supertab_recap(const char *tab,const char *lead,const char *chat_
snprintf(got_chat_id,sizeof got_chat_id,"%s",chat_id);snprintf(got_thread,sizeof got_thread,"%s",thread);
snprintf(got_text,sizeof got_text,"%s",text?text:"");got_at=at;got_none=none;
}
-static bool ui_supertab_notice(const char *tab,const char *lead,ht_chat_kind_t chat,const char *chat_id,const char *text,uint32_t at) {
+static bool ui_supertab_notice(const char *tab,const char *lead,ht_chat_kind_t chat,const char *chat_id,const char *thread,const char *text,uint32_t at) {
notice_calls++;snprintf(got_tab,sizeof got_tab,"%s",tab);snprintf(got_lead,sizeof got_lead,"%s",lead);got_chat=chat;
- snprintf(got_chat_id,sizeof got_chat_id,"%s",chat_id);snprintf(got_text,sizeof got_text,"%s",text);got_at=at;return beep_next;
+ snprintf(got_chat_id,sizeof got_chat_id,"%s",chat_id);snprintf(got_thread,sizeof got_thread,"%s",thread);
+ snprintf(got_text,sizeof got_text,"%s",text);got_at=at;return beep_next;
}
static void ui_supertab_notice_read(const char *tab,const char *lead,const char *chat_id) {
read_calls++;snprintf(got_tab,sizeof got_tab,"%s",tab);snprintf(got_lead,sizeof got_lead,"%s",lead);
@@ -210,7 +211,16 @@ int main(void) {
feed(handle_supertab_notice,"{\"tab\":\"s1\",\"lead\":\"L2\",\"chat\":\"pm\",\"chatId\":\"pm1\",\"id\":\"m9\",\"text\":\"Ready to ship.\",\"at\":1792560000}");
beep_next=false;
assert(notice_calls==1 && beeps==beeps_before+1 && !strcmp(got_tab,"s1") && !strcmp(got_lead,"L2") && got_chat==HT_CHAT_PM);
- assert(!strcmp(got_chat_id,"pm1") && !strcmp(got_text,"Ready to ship.") && got_at==1792560000u);
+ assert(!strcmp(got_chat_id,"pm1") && !strcmp(got_text,"Ready to ship.") && got_at==1792560000u && !strcmp(got_thread,""));
+ // A reply inside a thread (#2463) names its root. One whose root cannot be held is still a thread's: no face shows it, so
+ // it beeps rather than reading as the main chat's; an empty one is the main stream.
+ feed(handle_supertab_notice,"{\"tab\":\"s1\",\"lead\":\"L2\",\"chat\":\"pm\",\"chatId\":\"pm1\",\"id\":\"m12\",\"text\":\"Fixed.\",\"at\":7,\"thread\":\"m9\"}");
+ assert(notice_calls==2 && !strcmp(got_thread,"m9") && !strcmp(got_text,"Fixed."));
+ feed(handle_supertab_notice,"{\"tab\":\"s1\",\"lead\":\"L2\",\"chat\":\"pm\",\"chatId\":\"pm1\",\"id\":\"m13\",\"text\":\"x\",\"at\":7,\"thread\":\"0123456789012345678901234567890123456789012345678901234567890123\"}");
+ assert(notice_calls==3 && got_thread[0]);
+ feed(handle_supertab_notice,"{\"tab\":\"s1\",\"lead\":\"L2\",\"chat\":\"pm\",\"chatId\":\"pm1\",\"id\":\"m14\",\"text\":\"x\",\"at\":7,\"thread\":\"\"}");
+ assert(notice_calls==4 && !strcmp(got_thread,""));
+ notice_calls=1;
feed(handle_supertab_notice,"{\"tab\":\"s1\",\"lead\":\"L1\",\"chat\":\"lead\",\"chatId\":\"lead-web\",\"id\":\"m10\",\"text\":\"Done.\",\"at\":5}");
assert(notice_calls==2 && got_chat==HT_CHAT_LEAD && beeps==beeps_before+1);
// The Buddy's word: chat "buddy" reaches the UI as HT_CHAT_BUDDY; the UI says it is quiet.
diff --git a/devices/harness-device/firmware/test/test_touch_ui.py b/devices/harness-device/firmware/test/test_touch_ui.py
index 01b02670a..6860875f0 100644
--- a/devices/harness-device/firmware/test/test_touch_ui.py
+++ b/devices/harness-device/firmware/test/test_touch_ui.py
@@ -1950,27 +1950,27 @@ static void swarm_chat_checks(const char *dir) {
// A notice for the face's chat is read at once and does not beep.
enter_at("s1", "C1");
- assert(!ui_supertab_notice("s1", "C1", HT_CHAT_PM, "pm1", "Shall I cut the release?", 1792560000u));
+ assert(!ui_supertab_notice("s1", "C1", HT_CHAT_PM, "pm1", "", "Shall I cut the release?", 1792560000u));
int e = swarm_entry("C1");
assert(e >= 0 && s.notice[e].read_on_dial && !s.notice[e].question && s.notice[e].swarm == 3);
assert(!strcmp(s.notice[e].summary, "Shall I cut the release?") && !strcmp(s.notice[e].name, "docs"));
assert(!strcmp(s.notice[e].machine, "openharness \xc2\xb7 PM"));
// A notice for another chat stays unread and beeps once: the Lead chat, while the face shows the PM chat.
- assert(ui_supertab_notice("s1", "C1", HT_CHAT_LEAD, "lead-docs", "Docs are merged.", 1792560001u));
+ assert(ui_supertab_notice("s1", "C1", HT_CHAT_LEAD, "lead-docs", "", "Docs are merged.", 1792560001u));
e = swarm_entry("C1");
assert(e >= 0 && !s.notice[e].read_on_dial && !strcmp(s.notice[e].summary, "Docs are merged."));
assert(!strcmp(s.notice[e].machine, "openharness"));
// Off the face: unread, and it beeps.
- assert(ui_supertab_notice("s1", "C2", HT_CHAT_LEAD, "lead-web", "Web is deployed.", 1792560002u));
+ assert(ui_supertab_notice("s1", "C2", HT_CHAT_LEAD, "lead-web", "", "Web is deployed.", 1792560002u));
assert(swarm_entry("C2") >= 0 && !s.notice[swarm_entry("C2")].read_on_dial);
// One entry per Lead: a second notice replaces the text and is unread again.
notice_mark_read(&s.notice[swarm_entry("C2")]);
- assert(ui_supertab_notice("s1", "C2", HT_CHAT_LEAD, "lead-web", "Web is rolled back.", 1792560003u));
+ assert(ui_supertab_notice("s1", "C2", HT_CHAT_LEAD, "lead-web", "", "Web is rolled back.", 1792560003u));
{ int count = 0; for (int i = 0; i < s.notice_count; i++) count += !strcmp(s.notice[i].agent_id, "C2"); assert(count == 1); }
e = swarm_entry("C2");
assert(!strcmp(s.notice[e].summary, "Web is rolled back.") && !s.notice[e].read_on_dial);
// A notice for a Lead the dial does not know is nothing.
- { int before = s.notice_count; assert(!ui_supertab_notice("s1", "nobody", HT_CHAT_LEAD, "x", "?", 1)); assert(s.notice_count == before); }
+ { int before = s.notice_count; assert(!ui_supertab_notice("s1", "nobody", HT_CHAT_LEAD, "x", "", "?", 1)); assert(s.notice_count == before); }
// It stays news across the desktop's inbox snapshot: kept, and not turned into a question.
{ cable_notif_t desk = {.agent_id = "a", .name = "Payments refactor", .summary = "Shipped."}; ui_notif_replace(&desk, 1); }
@@ -2271,6 +2271,35 @@ static void swarm_thread_checks(const char *dir) {
assert(!strcmp(sw.lead, "T1") && swarm_sent >= 1 && !strcmp(swarm_wire[0], "select s1 T1"));
puts("Swarm thread face: title, waiting, a recap only for the thread, swipe out sends the leave and the main recap ask and selects nothing, then swipes move on PASS");
}
+// A PM reply inside a thread (#2463, Diego 2026-10-29): read at once only while the face shows that very thread, else it beeps
+// and stays unread. A message in the main stream keeps today's rule: read at once while the face shows its chat.
+static void swarm_thread_notice_checks(void) {
+ reset(); ht_character_select(&character, HT_CHARACTER_FOCUS); fake_ms = 100000;
+ desk_open();
+ const char ids[1][ID_MAX] = {"s1"};
+ ui_supertabs_ids(ids, 1);
+ card_begin("s1", "t1", "openharness");
+ thread_lead("T0", "web-api", "m9", "Fix the login bug on Safari when the session expires", 1); thread_lead("T1", "firmware", "", "", -1); assert(!card_send());
+ enter_at("s1", "T0"); scene_take();
+ assert(!strcmp(sw.lead, "T0") && scene_says("Thread"));
+ // The face is in thread m9: a reply there is read at once and does not beep.
+ assert(!ui_supertab_notice("s1", "T0", HT_CHAT_PM, "pm1", "m9", "Fixed on Safari.", 1792560001u));
+ int e = swarm_entry("T0"); assert(e >= 0 && s.notice[e].read_on_dial && !strcmp(s.notice[e].summary, "Fixed on Safari."));
+ // A reply in another thread of that chat beeps and stays unread.
+ assert(ui_supertab_notice("s1", "T0", HT_CHAT_PM, "pm1", "m7", "The other task is merged.", 1792560002u));
+ e = swarm_entry("T0"); assert(e >= 0 && !s.notice[e].read_on_dial && !strcmp(s.notice[e].summary, "The other task is merged."));
+ ui_supertab_notice_read("s1", "T0", "pm1"); assert(swarm_entry("T0") < 0);
+ // The face back on the main chat: a thread reply beeps and stays unread, a main-stream one is read at once.
+ card_begin("s1", "t1", "openharness"); thread_lead("T0", "web-api", "", "", -1); thread_lead("T1", "firmware", "", "", -1); assert(!card_send());
+ scene_take(); assert(!strcmp(sw.lead, "T0") && !scene_says("Thread"));
+ assert(ui_supertab_notice("s1", "T0", HT_CHAT_PM, "pm1", "m9", "Fixed on Chrome too.", 1792560003u));
+ e = swarm_entry("T0"); assert(e >= 0 && !s.notice[e].read_on_dial);
+ assert(!ui_supertab_notice("s1", "T0", HT_CHAT_PM, "pm1", "", "Next: the release.", 1792560004u));
+ e = swarm_entry("T0"); assert(e >= 0 && s.notice[e].read_on_dial);
+ // Off the face, a thread reply beeps as any notice does.
+ assert(ui_supertab_notice("s1", "T1", HT_CHAT_PM, "pm1", "m9", "Flashed.", 1792560005u));
+ puts("Swarm thread notices: read at once only on that thread's face, a beep on the main chat or another thread, main-stream notices as before PASS");
+}
static void swarm_buddy_checks(const char *dir) {
// 7a the PM side: today's face and two dots, the upper one lit.
buddy_setup();
@@ -2324,7 +2353,7 @@ static void swarm_buddy_checks(const char *dir) {
ui_supertab_recap("s1", "B0", "b0", "", "Two ways: cache the read, or move it to the host. I'd cache it. Want me to write it up and send it to the PM?", 1792560000u, false);
scene_take(); assert(avatar() && card_top());
// With the bell too (an unread notice off the face) every run still fits the scene.
- assert(ui_supertab_notice("s1", "B1", HT_CHAT_LEAD, "lead-fw", "Flashed.", 1792560001u));
+ assert(ui_supertab_notice("s1", "B1", HT_CHAT_LEAD, "lead-fw", "", "Flashed.", 1792560001u));
scene_take(); assert(avatar() && scene.count < HT_RUNS);
ui_supertab_recap("s1", "B0", "b0", "", "", 1792560000u, true);
// Nothing said yet: whatever the face writes instead stands clear of the avatar, at any of its captions.
@@ -2360,7 +2389,7 @@ static void swarm_buddy_checks(const char *dir) {
int sent = swarm_sent; swipe_down();
assert(swarm_sent == sent + 1 && !strcmp(swarm_wire[sent], "side s1 pm") && pm_dots() && !lilac_ring() && !scene_says("No Buddy"));
// On the PM side an unread Lead notice still opens the inbox on a pull down.
- assert(ui_supertab_notice("s1", "B0", HT_CHAT_LEAD, "lead-web", "Web is merged.", 1792560001u));
+ assert(ui_supertab_notice("s1", "B0", HT_CHAT_LEAD, "lead-web", "", "Web is merged.", 1792560001u));
scene_take(); sent = swarm_sent; swipe_down();
assert(s.view == INBOX && swarm_sent == sent);
dispatch((action_t){.kind = A_HOME}); scene_take();
@@ -2430,7 +2459,7 @@ static void swarm_buddy_checks(const char *dir) {
scene_take(); pm_runs = scene.count;
assert(!badge() && pm_dots() && !offset_disc() && !scene_says("Your Buddy replied"));
int entries = s.notice_count; int woke = wakes;
- assert(!ui_supertab_notice("s1", "B0", HT_CHAT_BUDDY, "b0", "Cache it.", 1792560002u));
+ assert(!ui_supertab_notice("s1", "B0", HT_CHAT_BUDDY, "b0", "", "Cache it.", 1792560002u));
scene_take();
assert(s.notice_count == entries && wakes == woke && badge() && !pm_dots() && !offset_disc() && scene_says("Your Buddy replied") && scene.count == pm_runs);
FOCUS_PAGE("buddy-7d");
@@ -2441,18 +2470,18 @@ static void swarm_buddy_checks(const char *dir) {
swipe_up(); assert(!badge()); swipe_down(); assert(!badge() && !scene_says("Your Buddy replied"));
// The resting face keeps its own line on the lower arc: there the badge alone tells it.
ui_supertab_recap("s1", "B0", "lead-web", "", "", 1792560000u, true);
- assert(!ui_supertab_notice("s1", "B0", HT_CHAT_BUDDY, "b0", "Later.", 1792560002u));
+ assert(!ui_supertab_notice("s1", "B0", HT_CHAT_BUDDY, "b0", "", "Later.", 1792560002u));
scene_take(); assert(badge() && !offset_disc() && !scene_says("Your Buddy replied"));
swipe_up(); swipe_down(); assert(!badge() && pm_dots());
// A Buddy word while its side is open is read there; the desktop opening the Buddy chat reads one too.
swipe_up(); buddy_card("buddy");
- assert(!ui_supertab_notice("s1", "B0", HT_CHAT_BUDDY, "b0", "Done.", 1792560003u));
+ assert(!ui_supertab_notice("s1", "B0", HT_CHAT_BUDDY, "b0", "", "Done.", 1792560003u));
swipe_down(); assert(!badge());
- assert(!ui_supertab_notice("s1", "B0", HT_CHAT_BUDDY, "b0", "Again.", 1792560004u)); scene_take(); assert(badge());
+ assert(!ui_supertab_notice("s1", "B0", HT_CHAT_BUDDY, "b0", "", "Again.", 1792560004u)); scene_take(); assert(badge());
ui_supertab_notice_read("s1", "B0", "other"); scene_take(); assert(badge());
ui_supertab_notice_read("s1", "B0", "b0"); scene_take(); assert(!badge());
// A Lead notice is unchanged: an entry, and a beep off the face.
- assert(ui_supertab_notice("s1", "B1", HT_CHAT_LEAD, "lead-fw", "Flashed.", 1792560005u) && s.notice_count == entries + 1);
+ assert(ui_supertab_notice("s1", "B1", HT_CHAT_LEAD, "lead-fw", "", "Flashed.", 1792560005u) && s.notice_count == entries + 1);
// 7e-7g voice on the Buddy side: the Buddy's engine's pet, the ring kept, and "Sending to your Buddy".
buddy_setup(); swipe_up(); buddy_card("buddy"); scene_take();
@@ -4057,6 +4086,7 @@ int main(int argc, char **argv) {
swarm_restart_checks();
swarm_buddy_checks(argc>1 ? argv[1] : NULL);
swarm_thread_checks(argc>1 ? argv[1] : NULL);
+ swarm_thread_notice_checks();
}
'''
extra_sources = []
diff --git a/docs/plans/2026-11-03-thread-notice-alerts-plan.md b/docs/plans/2026-11-03-thread-notice-alerts-plan.md
new file mode 100644
index 000000000..aaa81736d
--- /dev/null
+++ b/docs/plans/2026-11-03-thread-notice-alerts-plan.md
@@ -0,0 +1,141 @@
+# A Thread Reply Alerts Unless That Very Thread Is Open Implementation Plan
+
+> **How this is worked:** by the project's instructions, task by task, each failing test committed before its code.
+
+**Goal:** A PM or Buddy reply inside a thread beeps and stays unread on the round dial while its chat is open on the desktop
+or on the dial's face, unless that very thread is open there. A message in the main stream behaves as today.
+
+**Architecture:** The dial's alert is a `LeadNotice` that `SwarmCards.raise` (cli/src/superTabs/cards.ts) makes from the
+newest agent message, thread replies included. It gains an optional `thread`: the root of the thread the message replies
+in, unset for a main-stream message, a thread's root, or a reply also sent to the chat. The cable session's `pushNotice`
+(cli/src/cable/cableSession.ts) today counts a notice as read on the desktop whenever the window has its chat open; it
+then also needs the window's `threadRoot` to be the notice's thread, both when the notice arrives (not sent) and later
+(`supertab.notice.read`). A swarmThread dial gets `thread` on `supertab.notice`; the firmware (cable_client.c,
+ui_habitat.c `ui_supertab_notice`) reads a thread notice at once only when the Lead's face shows that thread
+(`thread_root`), otherwise it beeps and stays unread. A dial without swarmThread gets today's frame. The held-notice
+`inChat` WeakSet in cards.ts says the same as `thread === undefined`, so it is replaced by the field.
+
+**Tech Stack:** TypeScript (Vitest) for the CLI and cable; C11 with the Python-driven host tests for the firmware
+(`devices/harness-device/firmware/test`).
+
+**Spec:** Task #2463 (Diego, reported 10-29; replaces closed PR #2222; builds on the thread face #2718/#2756 and tasks in
+threads #2704). Not done here: the brief's optional "tapping it enters that thread on the face".
+
+## Global Constraints
+
+- The PR body starts with: `Requested by [email protected] through Harness.`
+- Swarm code stays out of cli/src/core: the only core change is the generic optional `thread` on `LeadNotice`
+ (cli/src/core/api.ts).
+- Never publish firmware, run upload scripts or touch the device update manifest; the real-dial check is Diego's after
+ merge.
+- Compatibility: `thread` is optional everywhere. A dial without swarmThread gets the exact frame of today; old firmware
+ ignores an unknown key; a notice without `thread` keeps today's rule on desktop and dial.
+- Desktop tests use a memory store and a fake sign-in; nothing signs the Mac out of the real CLI.
+- Backend changes: none (no backend file changes), so the full Super Tab integration suite is not required; the CLI
+ coverage gate `npm run test:core` covers the touched core type.
+
+## Design
+
+- growth: N/A because the notice stays one held entry per Lead (and one Buddy entry), replaced by the next; nothing new
+ is stored.
+- concurrency: N/A because the notices are held in one process's memory and pushed on the session's one queue, as today.
+- read cost: no new read; the thread is a field of the message rows `raise` already has.
+- scale: N/A because one more short id on a frame; the frame is still cut to the dial's limit by `fitText`.
+- compatibility: optional field; the frame key is sent only to a swarmThread dial (see Global Constraints).
+- migration + rollback: N/A because nothing persists; rolling back restores today's behavior.
+- audience: unchanged; the notice is built from messages the reader can already read.
+- identity: unchanged.
+- failure: a notice whose thread is unknown on the dial beeps (the safe side), never silently reads.
+- platforms: CLI daemon on macOS, Linux and Windows; firmware on the round dial.
+
+## Review Focus
+
+1. A reply also sent to the chat, and a thread's root, are main-stream notices (Task 1 tests).
+2. The desktop with the chat open but another thread, or no thread, open: a thread notice is sent and not read; opening
+ that thread sends `notice.read` once (Task 2 tests).
+3. An older dial (no swarmThread) gets `supertab.notice` without `thread`, byte for byte as today (Task 2 test).
+4. The face showing the main chat beeps for a thread notice; the face in that thread reads it at once; a main-stream
+ notice keeps today's rule (Task 3 tests).
+5. The recap answered from a held notice (`held`) still never takes a thread reply for the chat's recap, now through
+ `notice.thread` (existing test "never answers the chat recap from a notice that is a thread reply").
+
+---
+
+### Task 1: The notice names its thread
+
+**Files:**
+- Modify: `cli/src/core/api.ts` (`LeadNotice`), `cli/src/superTabs/cards.ts` (`lastAgentMessage`, `raise`, `held`)
+- Test: `cli/src/superTabs/cards.spec.ts`
+
+**Interfaces:**
+- Produces: `LeadNotice.thread?: string`, the root of the thread the message replies in; absent for a main-stream
+ message. `lastAgentMessage` returns the message's `thread` when it is a reply only in a thread.
+
+- [ ] **Step 1: Write the failing tests** in `cards.spec.ts`, `describe('SwarmCards notices')`:
+ - `a PM reply inside a thread is a thread notice` — a new PM line with `thread: 'x1'` in the Buddy chat: the notice is
+ `{ chat: 'pm', chatId: 'pm-web', id: 'x2', ..., thread: 'x1' }`.
+ - `a thread reply also sent to the chat, or a thread's root, is no thread notice` — `alsoInChat: true`, and a root
+ (`thread` equal to its own id): the notice has no `thread`.
+- [ ] **Step 2: Run** `npx vitest run src/superTabs/cards.spec.ts` in `cli`: the first FAILS (no `thread`).
+- [ ] **Step 3: Commit** the failing tests and push.
+- [ ] **Step 4: Implement**: `thread?: string` on `LeadNotice`; `lastAgentMessage` returns `thread` for a row whose
+ `thread` is a string other than its id and not `alsoInChat`; `raise` copies it; `held` uses `notice.thread ===
+ undefined` and the `inChat` WeakSet goes.
+- [ ] **Step 5: Run** the file and `npx tsc --noEmit -p .`: PASS.
+- [ ] **Step 6: Commit and push.**
+
+### Task 2: The desktop reads a thread notice only in that thread; the frame carries it
+
+**Files:**
+- Modify: `cli/src/cable/cableSession.ts` (`noticeFrame`, `pushNotices`, `pushNotice`)
+- Test: `cli/src/cable/cableSession.spec.ts`
+
+**Interfaces:**
+- Consumes: `LeadNotice.thread` (Task 1); `activeSwarmProject().threadRoot`.
+- Produces: `supertab.notice` with `thread` for a swarmThread dial.
+
+- [ ] **Step 1: Write the failing tests** in `cableSession.spec.ts`, `describe('swarmThread')`:
+ - `a thread notice is sent while its chat is open, and read only when the window opens that thread` — the window on
+ `pm1` with no thread, then thread `other`: the notice is sent with `thread: 'r1'` and no `notice.read`; the window
+ opens `r1`: one `notice.read`.
+ - `a thread notice arriving while that thread is open is not sent` — noted as read.
+ - `a dial without swarmThread gets today's frame for a thread notice` — `supertab.notice` with no `thread` key.
+- [ ] **Step 2: Run** `npx vitest run src/cable/cableSession.spec.ts -t swarmThread` in `cli`: they FAIL.
+- [ ] **Step 3: Commit** the failing tests and push.
+- [ ] **Step 4: Implement**: `pushNotices` passes the window's open conversation and thread root; `pushNotice` counts a
+ notice as open on the desktop when the chat matches and, for a thread notice, the root matches; `noticeFrame` adds
+ `thread` when the session speaks swarmThread.
+- [ ] **Step 5: Run** the file and `npx tsc --noEmit -p .`: PASS.
+- [ ] **Step 6: Commit and push.**
+
+### Task 3: The face beeps for a thread reply unless it shows that thread
+
+**Files:**
+- Modify: `devices/harness-device/firmware/main/cable_client.c` (`handle_supertab_notice`),
+ `devices/harness-device/firmware/main/ui/ui_screens.h`, `devices/harness-device/firmware/main/ui/habitat/ui_habitat.c`
+ (`ui_supertab_notice`)
+- Test: `devices/harness-device/firmware/test/test_touch_ui.py`, `devices/harness-device/firmware/test/test_cable_supertab.py`
+
+**Interfaces:**
+- Produces: `ui_supertab_notice(tab, lead, chat, chat_id, thread, text, at)`; `thread` is "" for a main-stream notice.
+
+- [ ] **Step 1: Write the failing tests**:
+ - `test_touch_ui.py`, in the thread face checks: a PM thread notice for `m9` while T0's face shows the main PM chat
+ beeps and stays unread; while the face shows thread `m9` it is read at once and does not beep; one for another
+ thread while the face shows `m9` beeps.
+ - `test_cable_supertab.py`: `supertab.notice` with `thread` reaches the UI with it; without it, "".
+- [ ] **Step 2: Run** `python3 test/test_touch_ui.py` and `python3 test/test_cable_supertab.py` in the firmware folder: FAIL.
+- [ ] **Step 3: Commit** the failing tests and push.
+- [ ] **Step 4: Implement**: `handle_supertab_notice` reads `thread` ("" when absent; a root too long to hold is passed as it
+ is, so no face matches it and it beeps, as Design's failure line says); `ui_supertab_notice`
+ takes it; the face reads a notice at once only when it shows that chat and, for a thread notice, that thread. The
+ Buddy's quiet word keeps its rule.
+- [ ] **Step 5: Run** both files and `test/run.sh`: PASS.
+- [ ] **Step 6: Commit and push.**
+
+### Task 4: Evidence
+
+- [ ] Red/green evidence (each failing run before its code, then green) in a PR comment.
+- [ ] `npm run test:core` in `cli` (the touched core type), the cards and cable spec files, `npm run typecheck`, firmware
+ `test/run.sh`.
+- [ ] Mark the PR ready; add the review step.