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.

feat(dial): the Swarm tab on the round dial (#1625)

0xdiego25d923483b2cd6
diff --git a/devices/harness-device/firmware/main/CMakeLists.txt b/devices/harness-device/firmware/main/CMakeLists.txt
index 044187a11..04e65612f 100644
--- a/devices/harness-device/firmware/main/CMakeLists.txt
+++ b/devices/harness-device/firmware/main/CMakeLists.txt
@@ -49,6 +49,7 @@ set(BOARD_SRCS
"ui/habitat/terminal.c"
"ui/habitat/scroll.c"
"ui/habitat/workspace.c"
+ "ui/habitat/supertab.c"
"ui/habitat/selection.c"
"ui/habitat/carry.c"
"ui/habitat/visit.c"
diff --git a/devices/harness-device/firmware/main/cable_client.c b/devices/harness-device/firmware/main/cable_client.c
index 42d164b07..f27add12a 100644
--- a/devices/harness-device/firmware/main/cable_client.c
+++ b/devices/harness-device/firmware/main/cable_client.c
@@ -24,6 +24,8 @@
#include "freertos/semphr.h"
#include "freertos/task.h"
#include "ui/ui_screens.h"
+#include "ui/habitat/supertab.h"
+#include "esp_attr.h"
static const char *TAG = "cable_client";
@@ -315,6 +317,10 @@ static void send_hello(void)
// Named before anything else about this dial is believed. See CABLE_PRODUCT.
msg_string(&root, "product", CABLE_PRODUCT);
msg_number(&root, "proto", CABLE_PROTO_VERSION);
+ // The Swarms (handle_supertab) and their Super Tab waits (handle_question). Without the second the daemon holds
+ // a wait back from this dial, which once had to: a wait is never an answer screen here.
+ msg_string(&root, "swarmCard", "v1");
+ msg_string(&root, "superTab", "wait-v1");
// Which of the two dials this is (board.h) — informational, so a log or a bug report can say. A
// daemon that predates the field ignores it.
msg_string(&root, "hw", board()->name);
@@ -372,6 +378,18 @@ void cable_client_list_swarms(void)
send_json(msg("swarms.list"));
}
+void cable_client_supertab_send(const char *t, const char *tab, const char *lead)
+{
+ if (!t || (strcmp(t, "supertab.recap.get") && strcmp(t, "supertab.open") && strcmp(t, "supertab.select"))) return;
+ // Only an open may name no Lead: it says the dial left the Swarm.
+ if (!tab || !tab[0] || strlen(tab) >= ID_MAX || !lead || strlen(lead) >= ID_MAX ||
+ (!lead[0] && strcmp(t, "supertab.open"))) return;
+ cJSON *root = msg(t);
+ msg_string(&root, "tab", tab);
+ msg_string(&root, "lead", lead);
+ send_json(root);
+}
+
void cable_client_send_turn(const char *agent_id, const char *text)
{
@@ -895,6 +913,106 @@ static void handle_swarms(const cJSON *p)
* app's own shape and needs every one of them. */
}
+// ── the Swarms ──────────────────────────────────────────────────────────────────────────────────────
+// Two frames, as for the Pro, so each stays under the JSON guard: `supertabs` {ids} is the set and its order,
+// `supertab` one Swarm with at most 12 Leads. A Swarm without a usable id is dropped; a Lead that is not an
+// object, has no usable id or repeats one is skipped and the frame survives.
+static bool id_fits(const char *s)
+{
+ return s && s[0] && strlen(s) < ID_MAX;
+}
+static void handle_supertabs(const cJSON *p)
+{
+ const cJSON *ids = cJSON_GetObjectItemCaseSensitive(p, "ids");
+ if (!cJSON_IsArray(ids)) return;
+ static EXT_RAM_BSS_ATTR char rows[HT_SUPERTABS_MAX][ID_MAX];
+ int n = 0;
+ const cJSON *it = NULL;
+ cJSON_ArrayForEach(it, ids) {
+ if (n >= HT_SUPERTABS_MAX) break;
+ if (!cJSON_IsString(it) || !id_fits(it->valuestring)) continue;
+ bool duplicate = false;
+ for (int i = 0; i < n; i++) if (!strcmp(rows[i], it->valuestring)) duplicate = true;
+ if (!duplicate) snprintf(rows[n++], ID_MAX, "%s", it->valuestring);
+ }
+ ESP_LOGI(TAG, "supertabs: %d", n);
+ ui_supertabs_ids((const char (*)[ID_MAX])rows, n);
+}
+static void handle_supertab(const cJSON *p)
+{
+ static EXT_RAM_BSS_ATTR ht_supertab_t card; // 3.4 KB: too large for the reader task's stack
+ const char *tab = str_of(p, "tab");
+ if (tab && strlen(tab) >= ID_MAX) tab = ""; // a desk tab id that cannot be held links to nothing
+ if (!ht_supertab_init(&card, str_of(p, "id"), tab, str_of(p, "name"), 0)) return;
+ const cJSON *l = NULL;
+ cJSON_ArrayForEach(l, cJSON_GetObjectItemCaseSensitive(p, "leads")) {
+ if (card.lead_n >= HT_SUPERTAB_LEADS_MAX) break;
+ if (!cJSON_IsObject(l)) continue;
+ const cJSON *order = cJSON_GetObjectItemCaseSensitive(l, "order"), *since = cJSON_GetObjectItemCaseSensitive(l, "since");
+ ht_lead_in_t in = {
+ .id = str_of(l, "id"), .project_id = str_of(l, "projectId"), .project = str_of(l, "project"),
+ .engine = str_of(l, "engine"), .owner = str_of(l, "owner"), .local = str_of(l, "local"), .state = str_of(l, "state"),
+ // Absent from a daemon before `order`: the frame's own order stands.
+ .order = cJSON_IsNumber(order) && order->valuedouble >= 0 && order->valuedouble < 65536 ? (int)order->valuedouble : -1,
+ .since = cJSON_IsNumber(since) && since->valuedouble >= 0 ? (since->valuedouble > 2592000 ? 2592000 : (long)since->valuedouble) : -1,
+ };
+ ht_supertab_lead_add(&card, &in);
+ }
+ const cJSON *count = cJSON_GetObjectItemCaseSensitive(p, "count"); // absent: the Leads listed
+ card.count = cJSON_IsNumber(count) ? (count->valuedouble > 0 ? (count->valuedouble > 65535 ? 65535 : (uint16_t)count->valuedouble) : 0)
+ : card.lead_n;
+ // A Lead that starts needing a person, off the face: the same coalesced beep as a question.
+ if (ui_supertab(&card)) audio_notify_done();
+}
+// `supertab.recap`: one Lead's last message. The model cuts it to 1,500 bytes; `none` is "no message yet".
+static void handle_supertab_recap(const cJSON *p)
+{
+ const char *tab = str_of(p, "tab"), *lead = str_of(p, "lead"), *text = str_of(p, "text");
+ if (!id_fits(tab) || !id_fits(lead)) return;
+ const cJSON *at = cJSON_GetObjectItemCaseSensitive(p, "at");
+ const double secs = cJSON_IsNumber(at) && at->valuedouble > 0 ? at->valuedouble : 0;
+ const bool none = cJSON_IsTrue(cJSON_GetObjectItemCaseSensitive(p, "none"));
+ ui_supertab_recap(tab, lead, none || !text ? "" : text, secs > 4294967295.0 ? 0xFFFFFFFFu : (uint32_t)secs, none);
+}
+static void handle_supertab_focus(const cJSON *p)
+{
+ const char *tab = str_of(p, "tab"), *lead = str_of(p, "lead");
+ if (id_fits(tab) && id_fits(lead)) ui_supertab_focus(tab, lead);
+}
+
+// `question` {agentId, id, questions, superTab?, attention?}. With a non-empty `superTab` it is a Super Tab wait: the
+// dial cannot load its answer screen, so it only changes the asking Lead's inbox entry and face (ui_supertab_wait).
+static void handle_question(const cJSON *p, const char *agent_id)
+{
+ const cJSON *questions = cJSON_GetObjectItemCaseSensitive(p, "questions");
+ const char *swarm = str_of(p, "superTab");
+ if (agent_id && swarm && swarm[0]) {
+ const char *request = str_of(p, "id"), *attention = str_of(p, "attention");
+ if (!request || !request[0] || strlen(request) >= 64) return;
+ if (ui_supertab_wait(agent_id, request, swarm, attention && !strcmp(attention, "stuck"),
+ str_of(cJSON_GetArrayItem(questions, 0), "q")))
+ audio_notify_done();
+ return;
+ }
+ // The name rides on the frame for the same reason as on `summary`: the asker may be off this tab.
+ if (agent_id && questions) {
+ // A question is an alert: pinned row, wake and a (coalesced) beep, all but the beep inside
+ // ui_question_show, which stays quiet for the pane already on the glass.
+ if (ui_question_show(agent_id, str_of(p, "name"), str_of(p, "machine"), str_of(p, "id"), questions))
+ audio_notify_done();
+ }
+}
+// Somebody else answered it. A question is a dialog in a tmux pane, not a shared object, so this is
+// the ONLY way the dial learns that the thing it is waiting on has already been dealt with — without
+// it the screen sits there offering options that no longer key into anything.
+static void handle_question_close(const cJSON *p, const char *agent_id)
+{
+ const char *request = str_of(p, "id");
+ if (!agent_id) return;
+ if (request && !strncmp(request, "supertab:", 9)) ui_supertab_wait_close(agent_id, request);
+ else ui_question_close(agent_id, request);
+}
+
static void session_up(const cJSON *p)
{
atomic_store(&s_features, cable_features_parse(p));
@@ -960,6 +1078,8 @@ static void session_down(const char *why)
// alone deliberately: a session that comes back on the same computer should land where it was.
cable_machines_clear(&s_machines);
ui_machines_clear();
+ // The Swarms too, with their inbox entries: on attach the daemon resends every card and every open wait.
+ ui_supertabs_clear();
s_machine_name[0] = '\0';
s_machine_id[0] = '\0';
// Restore the plain console FIRST: whatever follows this point should be readable by a developer with
@@ -1248,6 +1368,10 @@ static void handle_message(const cJSON *root)
if (strcmp(t, "settings.set") == 0) { handle_settings_set(p); return; }
if (strcmp(t, "models") == 0) { handle_models(p); return; }
if (strcmp(t, "swarms") == 0) { handle_swarms(p); return; }
+ if (strcmp(t, "supertabs") == 0) { handle_supertabs(p); return; }
+ if (strcmp(t, "supertab") == 0) { handle_supertab(p); return; }
+ if (strcmp(t, "supertab.recap") == 0) { handle_supertab_recap(p); return; }
+ if (strcmp(t, "supertab.focus") == 0) { handle_supertab_focus(p); return; }
if (strcmp(t, "agent.updated") == 0) {
// One agent changed. Cheapest correct answer is to re-ask: the daemon is on the other end of a
@@ -1341,24 +1465,8 @@ static void handle_message(const cJSON *root)
}
if (strcmp(t,"question.state")==0) { ui_question_state(p); return; }
if (strcmp(t,"answer.receipt")==0) { ui_answer_receipt(p); return; }
- if (strcmp(t, "question") == 0) {
- const cJSON *questions = cJSON_GetObjectItemCaseSensitive(p, "questions");
- // The name rides on the frame for the same reason as on `summary`: the asker may be off this tab.
- if (agent_id && questions) {
- // A question is an alert: pinned row, wake and a (coalesced) beep, all but the beep inside
- // ui_question_show, which stays quiet for the pane already on the glass.
- if (ui_question_show(agent_id, str_of(p, "name"), str_of(p, "machine"), str_of(p, "id"), questions))
- audio_notify_done();
- }
- return;
- }
- // Somebody else answered it. A question is a dialog in a tmux pane, not a shared object, so this is
- // the ONLY way the dial learns that the thing it is waiting on has already been dealt with — without
- // it the screen sits there offering options that no longer key into anything.
- if (strcmp(t, "question.close") == 0) {
- if (agent_id) ui_question_close(agent_id, str_of(p, "id"));
- return;
- }
+ if (strcmp(t, "question") == 0) { handle_question(p, agent_id); return; }
+ if (strcmp(t, "question.close") == 0) { handle_question_close(p, agent_id); return; }
if (strcmp(t,"draft.state")==0) { ui_draft_state(p);return; }
if (strcmp(t,"voice.draft")==0) {
diff --git a/devices/harness-device/firmware/main/cable_client.h b/devices/harness-device/firmware/main/cable_client.h
index f1ed5fa87..80afa567a 100644
--- a/devices/harness-device/firmware/main/cable_client.h
+++ b/devices/harness-device/firmware/main/cable_client.h
@@ -210,6 +210,7 @@ typedef struct {
bool read_on_dial;
uint32_t display_revision;
uint32_t received_ms; // ms() when the row was filed; rows expire 6 h later (notice_expire)
+ uint8_t swarm; // the dial's own Swarm entry, kept across notif.replace: 1 needs you, 2 stuck (0 the desktop's)
} cable_notif_t;
bool cable_client_notification_read(const char *agent_id, const char *read_token);
@@ -219,6 +220,20 @@ void cable_client_select_swarm(const char *swarm_id);
// Re-ask for the list (a screen that just opened wants it fresh).
void cable_client_list_swarms(void);
+// ── the Swarms (Super Tabs), named by `swarmCard:"v1"` and `superTab:"wait-v1"` in the hello ───────────
+// The Harness Pro's frames, unchanged (cli/src/cable/cableSession.ts; devices/harness-pro/docs/cable.md):
+// in supertabs {ids} the Swarms and their order, ≤16, the desktop's open ones first
+// supertab {id, tab, name, count, leads:[{id, projectId, project, engine, owner, local, state, since?, order?}]}
+// one Swarm, ≤12 Leads; `tab` is its desk tab or ""; `order` is the project's
+// place in the app (absent from an older daemon: the frame's order)
+// supertab.recap {tab, lead, text, at, none} the open Lead's last message
+// supertab.focus {tab, lead} the desktop moved to that Lead
+// question {…, superTab, attention} a Super Tab wait (id "supertab:…"); never an answer screen here
+// out supertab.recap.get / supertab.open / supertab.select {tab, lead}
+// A Lead id is not an agent id: it never goes into focus, agent.open or voice.begin. Only its `local` harness id does.
+// `t` is one of the three requests; `lead` is "" only for an open (the dial left the Swarm).
+void cable_client_supertab_send(const char *t, const char *tab, const char *lead);
+
// Send what the user asked for, into `agent_id`. Fire-and-forget: everything after this arrives back as
// `turn.started` / `turn.done`, or as `turn.error` in words a person can act on.
void cable_client_send_turn(const char *agent_id, const char *text);
diff --git a/devices/harness-device/firmware/main/ui/habitat/supertab.c b/devices/harness-device/firmware/main/ui/habitat/supertab.c
new file mode 100644
index 000000000..276182614
--- /dev/null
+++ b/devices/harness-device/firmware/main/ui/habitat/supertab.c
@@ -0,0 +1,179 @@
+#include "supertab.h"
+#include <stdio.h>
+#include <string.h>
+
+// Copies at most size-1 bytes and never splits a UTF-8 sequence.
+static void put_text(char *dst, size_t size, const char *src)
+{
+ size_t n = src ? strlen(src) : 0;
+ if (n >= size) {
+ n = size - 1;
+ while (n && ((unsigned char)src[n] & 0xC0) == 0x80) n--;
+ }
+ if (n) memcpy(dst, src, n);
+ dst[n] = 0;
+}
+static bool put_id(char *dst, const char *src, bool required)
+{
+ size_t n = src ? strlen(src) : 0;
+ if (n >= ID_MAX || (required && !n)) return false;
+ put_text(dst, ID_MAX, src);
+ return true;
+}
+static bool asking(ht_lead_state_t s)
+{
+ return s == HT_LEAD_ASK || s == HT_LEAD_STUCK;
+}
+static int emit(ht_lead_event_t *ev, int ev_max, int n, ht_lead_event_kind_t kind, const char *tab, const char *lead)
+{
+ if (!ev || n >= ev_max) return n;
+ ev[n].kind = kind;
+ snprintf(ev[n].tab, sizeof ev[n].tab, "%s", tab);
+ snprintf(ev[n].lead, sizeof ev[n].lead, "%s", lead);
+ return n + 1;
+}
+
+bool ht_supertab_init(ht_supertab_t *t, const char *id, const char *tab, const char *name, int count)
+{
+ memset(t, 0, sizeof *t);
+ if (!put_id(t->id, id, true) || !put_id(t->tab, tab, false)) return false;
+ put_text(t->name, sizeof t->name, name);
+ t->count = count < 0 ? 0 : count > UINT16_MAX ? UINT16_MAX : (uint16_t)count;
+ return true;
+}
+bool ht_supertab_lead_add(ht_supertab_t *t, const ht_lead_in_t *in)
+{
+ if (t->lead_n >= HT_SUPERTAB_LEADS_MAX) return false;
+ for (int i = 0; in->id && i < t->lead_n; i++) if (!strcmp(t->leads[i].id, in->id)) return false; // a repeated id
+ ht_lead_t *l = &t->leads[t->lead_n];
+ memset(l, 0, sizeof *l);
+ if (!put_id(l->id, in->id, true) || !put_id(l->project_id, in->project_id, false) ||
+ !put_id(l->local, in->local, false)) return false;
+ put_text(l->project, sizeof l->project, in->project);
+ put_text(l->engine, sizeof l->engine, in->engine);
+ put_text(l->owner, sizeof l->owner, in->owner);
+ const char *s = in->state ? in->state : "";
+ l->state = !strcmp(s, "ask") ? HT_LEAD_ASK : !strcmp(s, "stuck") ? HT_LEAD_STUCK :
+ !strcmp(s, "work") ? HT_LEAD_WORK : HT_LEAD_DONE;
+ l->order = in->order < 0 ? -1 : in->order;
+ l->since_s = in->since < 0 ? -1 : in->since > INT32_MAX ? INT32_MAX : (int32_t)in->since;
+ t->lead_n++;
+ return true;
+}
+
+void ht_supertabs_reset(ht_supertabs_t *s)
+{
+ memset(s, 0, sizeof *s);
+}
+const ht_supertab_t *ht_supertabs_find(const ht_supertabs_t *s, const char *id)
+{
+ if (!id || !*id) return NULL;
+ for (int i = 0; i < s->n; i++) if (!strcmp(s->tabs[i].id, id)) return &s->tabs[i];
+ return NULL;
+}
+const ht_supertab_t *ht_supertabs_at(const ht_supertabs_t *s, int i)
+{
+ for (int k = 0; k < s->id_n; k++) {
+ const ht_supertab_t *t = ht_supertabs_find(s, s->ids[k]);
+ if (t && i-- == 0) return t;
+ }
+ return NULL;
+}
+const ht_supertab_t *ht_supertabs_for_desk(const ht_supertabs_t *s, const char *desk_tab_id)
+{
+ if (!desk_tab_id || !*desk_tab_id) return NULL;
+ for (int i = 0; i < s->n; i++) if (!strcmp(s->tabs[i].tab, desk_tab_id)) return &s->tabs[i];
+ return NULL;
+}
+const ht_lead_t *ht_supertabs_lead_by_local(const ht_supertabs_t *s, const char *harness_id, const ht_supertab_t **tab)
+{
+ if (!harness_id || !*harness_id) return NULL;
+ for (int i = 0; i < s->n; i++) for (int k = 0; k < s->tabs[i].lead_n; k++)
+ if (!strcmp(s->tabs[i].leads[k].local, harness_id)) {
+ if (tab) *tab = &s->tabs[i];
+ return &s->tabs[i].leads[k];
+ }
+ return NULL;
+}
+
+int ht_supertabs_ids(ht_supertabs_t *s, const char ids[][ID_MAX], int n, ht_lead_event_t *ev, int ev_max)
+{
+ s->id_n = 0;
+ for (int i = 0; i < n && s->id_n < HT_SUPERTABS_MAX; i++)
+ if (ids[i][0] && memchr(ids[i], 0, ID_MAX)) snprintf(s->ids[s->id_n++], ID_MAX, "%s", ids[i]);
+ int events = 0, kept = 0;
+ for (int i = 0; i < s->n; i++) {
+ bool listed = false;
+ for (int k = 0; k < s->id_n && !listed; k++) listed = !strcmp(s->ids[k], s->tabs[i].id);
+ if (listed) {
+ if (kept != i) s->tabs[kept] = s->tabs[i];
+ kept++;
+ continue;
+ }
+ for (int k = 0; k < s->tabs[i].lead_n; k++)
+ if (asking(s->tabs[i].leads[k].state))
+ events = emit(ev, ev_max, events, HT_LEAD_CLEARED, s->tabs[i].id, s->tabs[i].leads[k].id);
+ }
+ s->n = kept;
+ return events;
+}
+
+int ht_supertabs_put(ht_supertabs_t *s, const ht_supertab_t *in, uint32_t now_ms, ht_lead_event_t *ev, int ev_max)
+{
+ bool listed = false;
+ for (int k = 0; k < s->id_n && !listed; k++) listed = !strcmp(s->ids[k], in->id);
+ if (!listed) return 0;
+ ht_supertab_t *t = (ht_supertab_t *)ht_supertabs_find(s, in->id);
+ if (!t) {
+ if (s->n >= HT_SUPERTABS_MAX) return 0;
+ t = &s->tabs[s->n++];
+ t->lead_n = 0;
+ }
+ int events = 0;
+ for (int i = 0; i < in->lead_n; i++) {
+ const ht_lead_t *was = NULL;
+ for (int k = 0; k < t->lead_n && !was; k++) if (!strcmp(t->leads[k].id, in->leads[i].id)) was = &t->leads[k];
+ ht_lead_state_t now = in->leads[i].state;
+ if (asking(now) && (!was || was->state != now))
+ events = emit(ev, ev_max, events, now == HT_LEAD_ASK ? HT_LEAD_RAISED_ASK : HT_LEAD_RAISED_STUCK, in->id, in->leads[i].id);
+ else if (!asking(now) && was && asking(was->state))
+ events = emit(ev, ev_max, events, HT_LEAD_CLEARED, in->id, in->leads[i].id);
+ }
+ for (int k = 0; k < t->lead_n; k++) {
+ if (!asking(t->leads[k].state)) continue;
+ bool kept = false;
+ for (int i = 0; i < in->lead_n && !kept; i++) kept = !strcmp(t->leads[k].id, in->leads[i].id);
+ if (!kept) events = emit(ev, ev_max, events, HT_LEAD_CLEARED, in->id, t->leads[k].id);
+ }
+ *t = *in;
+ if (t->lead_n > HT_SUPERTAB_LEADS_MAX) t->lead_n = HT_SUPERTAB_LEADS_MAX;
+ // Insertion sort: stable, so equal (or absent) orders keep the frame's order.
+ for (int i = 1; i < t->lead_n; i++) {
+ ht_lead_t l = t->leads[i];
+ int k = i;
+ for (; k > 0 && t->leads[k - 1].order > l.order; k--) t->leads[k] = t->leads[k - 1];
+ t->leads[k] = l;
+ }
+ for (int i = 0; i < t->lead_n; i++) t->leads[i].since_at_ms = now_ms;
+ return events;
+}
+
+void ht_supertabs_recap_open(ht_supertabs_t *s, const char *tab, const char *lead, uint32_t now_ms)
+{
+ bool open = lead && *lead && tab && *tab;
+ put_text(s->recap.tab, sizeof s->recap.tab, open ? tab : "");
+ put_text(s->recap.lead, sizeof s->recap.lead, open ? lead : "");
+ s->recap.text[0] = 0;
+ s->recap.at = 0;
+ s->recap.asked_ms = now_ms;
+ s->recap.state = open ? HT_RECAP_LOADING : HT_RECAP_NONE;
+}
+bool ht_supertabs_recap_put(ht_supertabs_t *s, const char *tab, const char *lead, const char *text, uint32_t at, bool none)
+{
+ if (s->recap.state == HT_RECAP_NONE || !tab || !lead || strcmp(s->recap.tab, tab) || strcmp(s->recap.lead, lead))
+ return false;
+ put_text(s->recap.text, sizeof s->recap.text, none ? "" : text);
+ s->recap.at = at;
+ s->recap.state = s->recap.text[0] ? HT_RECAP_LOADED : HT_RECAP_EMPTY;
+ return true;
+}
diff --git a/devices/harness-device/firmware/main/ui/habitat/supertab.h b/devices/harness-device/firmware/main/ui/habitat/supertab.h
new file mode 100644
index 000000000..ba028759e
--- /dev/null
+++ b/devices/harness-device/firmware/main/ui/habitat/supertab.h
@@ -0,0 +1,60 @@
+// The Swarms (Super Tabs) and their Leads, as the daemon's `supertabs`/`supertab` frames describe them.
+// Pure: no LVGL and no cJSON. cable_client.c parses a frame into an ht_supertab_t with the two builders
+// below and the UI keeps the result here.
+#pragma once
+#include <stdbool.h>
+#include <stdint.h>
+
+#ifndef ID_MAX
+#define ID_MAX 48 // the same value as cable_client.h, which a pure module cannot include
+#endif
+
+enum { HT_SUPERTABS_MAX = 16, HT_SUPERTAB_LEADS_MAX = 12, HT_SUPERTAB_NAME = 49, HT_SUPERTAB_TEXT = 1501 };
+typedef enum { HT_LEAD_DONE, HT_LEAD_WORK, HT_LEAD_ASK, HT_LEAD_STUCK } ht_lead_state_t;
+typedef struct {
+ char id[ID_MAX], project_id[ID_MAX], project[HT_SUPERTAB_NAME], engine[12], owner[HT_SUPERTAB_NAME], local[ID_MAX];
+ ht_lead_state_t state;
+ int order; // -1 from a daemon that does not send it
+ int32_t since_s; // -1 when the daemon sent none (a remote Lead)
+ uint32_t since_at_ms; // the dial's clock when since_s arrived
+} ht_lead_t;
+typedef struct {
+ char id[ID_MAX], tab[ID_MAX], name[HT_SUPERTAB_NAME];
+ uint16_t count; // the Swarm's real project count; at most 12 Leads come
+ uint8_t lead_n;
+ ht_lead_t leads[HT_SUPERTAB_LEADS_MAX];
+} ht_supertab_t;
+typedef enum { HT_RECAP_NONE, HT_RECAP_LOADING, HT_RECAP_LOADED, HT_RECAP_EMPTY } ht_recap_state_t;
+typedef struct {
+ ht_supertab_t tabs[HT_SUPERTABS_MAX]; // the records that have arrived, in arrival order
+ int n;
+ char ids[HT_SUPERTABS_MAX][ID_MAX]; // the last `supertabs` list: the order Swarms are shown in
+ int id_n;
+ // One slot: the recap of the Lead on the face, and nothing else.
+ struct { char tab[ID_MAX], lead[ID_MAX], text[HT_SUPERTAB_TEXT]; uint32_t at, asked_ms; ht_recap_state_t state; } recap;
+} ht_supertabs_t;
+typedef enum { HT_LEAD_RAISED_ASK, HT_LEAD_RAISED_STUCK, HT_LEAD_CLEARED } ht_lead_event_kind_t;
+typedef struct { ht_lead_event_kind_t kind; char tab[ID_MAX], lead[ID_MAX]; } ht_lead_event_t;
+
+// One Lead of a frame, as read off the wire. NULL strings are absent fields.
+typedef struct { const char *id, *project_id, *project, *engine, *owner, *local, *state; int order; long since; } ht_lead_in_t;
+// false: an empty or overlong id or tab. Names are cut on a UTF-8 boundary.
+bool ht_supertab_init(ht_supertab_t *, const char *id, const char *tab, const char *name, int count);
+// false: the Lead is malformed or repeats an id (skipped, not the frame), or the record already holds 12.
+bool ht_supertab_lead_add(ht_supertab_t *, const ht_lead_in_t *);
+
+void ht_supertabs_reset(ht_supertabs_t *);
+// Drops records gone from the list; their asking Leads come back as CLEARED events. Returns the event count.
+int ht_supertabs_ids(ht_supertabs_t *, const char ids[][ID_MAX], int n, ht_lead_event_t *ev, int ev_max);
+// Sorts the Leads by order (stable, so frame order without it) and returns the transition events:
+// a Lead entering ask or stuck (also when first seen), and an asking Lead leaving ask/stuck or the frame.
+int ht_supertabs_put(ht_supertabs_t *, const ht_supertab_t *in, uint32_t now_ms, ht_lead_event_t *ev, int ev_max);
+const ht_supertab_t *ht_supertabs_find(const ht_supertabs_t *, const char *id);
+// The i-th Swarm of the list whose record has arrived.
+const ht_supertab_t *ht_supertabs_at(const ht_supertabs_t *, int i);
+const ht_supertab_t *ht_supertabs_for_desk(const ht_supertabs_t *, const char *desk_tab_id);
+const ht_lead_t *ht_supertabs_lead_by_local(const ht_supertabs_t *, const char *harness_id, const ht_supertab_t **tab);
+// LOADING with no text; an empty lead closes the slot (NONE).
+void ht_supertabs_recap_open(ht_supertabs_t *, const char *tab, const char *lead, uint32_t now_ms);
+// false: not the open Lead.
+bool ht_supertabs_recap_put(ht_supertabs_t *, const char *tab, const char *lead, const char *text, uint32_t at, bool none);
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 fff276ab1..591ad6106 100644
--- a/devices/harness-device/firmware/main/ui/habitat/ui_habitat.c
+++ b/devices/harness-device/firmware/main/ui/habitat/ui_habitat.c
@@ -3,6 +3,7 @@
#include "runtime.h"
#include "scroll.h"
#include "workspace.h"
+#include "supertab.h"
#include "selection.h"
#include "carry.h"
#include "visit.h"
@@ -129,7 +130,9 @@ typedef enum {
A_SELECT_BEGIN, A_SELECT_FIND, A_SELECT_EXTEND, A_SELECT_SEND, A_RETURN, A_LATEST, A_VISIT_SEND,
A_CARRY, A_CARRY_DROP, A_CARRY_SEND,
A_DRAFT_EDIT, A_DRAFT_APPEND, A_DRAFT_UNDO, A_DRAFT_SEND, A_DRAFT_DISCARD,
- A_DRAFT_STATE, A_DRAFT_OPTIONS, A_DRAFT_BACK, A_DRAFT_COMMAND, A_NOTICE_READ
+ A_DRAFT_STATE, A_DRAFT_OPTIONS, A_DRAFT_BACK, A_DRAFT_COMMAND, A_NOTICE_READ,
+ A_LEAD, // a Swarm's project picked on PANES: value its place, id its Lead
+ A_SUPERTAB // to the worker: value SUPERTAB_*, text the Swarm, id the Lead ("" only for an open)
} action_kind_t;
typedef struct {
action_kind_t kind;
@@ -579,11 +582,163 @@ static int workspace_index(const char *id)
for (int i=0;i<s.tab_count;i++) if (!strcmp(id,s.tabs[i].id)) return i;
return -1;
}
+/*
+ * THE SWARMS (Super Tabs; docs/superpowers/specs/2026-10-23-round-swarm-tab-design.md). A Swarm is one more tab: its
+ * projects are panes, each showing its Lead, in the app's order. `swarm` holds what the daemon said (supertab.c), `sw`
+ * where the dial is in it. A Lead id is not an agent id: it reaches the cable only in supertab.* requests (A_SUPERTAB),
+ * never in focus, agent.open or voice.begin. Voice goes to the Lead's `local` harness id.
+ */
+enum { SUPERTAB_RECAP_GET, SUPERTAB_OPEN, SUPERTAB_SELECT };
+#define SWARM_WAITS 16
+static EXT_RAM_BSS_ATTR ht_supertabs_t swarm;
+static EXT_RAM_BSS_ATTR struct {
+ char tab[ID_MAX], lead[ID_MAX]; // the Swarm the dial is in ("" in a desk tab) and the Lead on its face
+ int at; // that Lead's place, where the face lands when the Lead goes
+ bool retried; // its recap was asked for a second time
+ struct { char tab[ID_MAX], lead[ID_MAX]; } focus[HT_SUPERTABS_MAX]; // the Lead the desktop last showed, per Swarm
+ // Super Tab waits from this machine's harnesses, shown only through the Lead whose `local` names the harness.
+ struct { char agent[ID_MAX], request[80], swarm[HT_SUPERTAB_NAME], text[240]; bool stuck, shown; } waits[SWARM_WAITS];
+} sw;
+static bool swarm_mode(void)
+{
+ return sw.tab[0] != 0;
+}
+static const ht_supertab_t *swarm_here(void)
+{
+ return swarm_mode() ? ht_supertabs_find(&swarm, sw.tab) : NULL;
+}
+static int swarm_lead_index(const ht_supertab_t *t, const char *lead)
+{
+ for (int i = 0; t && lead && i < t->lead_n; i++) if (!strcmp(t->leads[i].id, lead)) return i;
+ return -1;
+}
+static const ht_lead_t *swarm_lead(void)
+{
+ const ht_supertab_t *t = swarm_here();
+ int i = swarm_lead_index(t, sw.lead);
+ return i >= 0 ? &t->leads[i] : NULL;
+}
+static const char *swarm_fixed_text(bool stuck)
+{
+ return stuck ? "Stuck. See the desktop." : "Needs you. Answer on the desktop.";
+}
+static int swarm_wait_of(const char *agent)
+{
+ for (int i = 0; agent && agent[0] && i < SWARM_WAITS; i++) if (!strcmp(sw.waits[i].agent, agent)) return i;
+ return -1;
+}
+static const char *swarm_wait_text(const ht_lead_t *l)
+{
+ int w = l ? swarm_wait_of(l->local) : -1;
+ return w < 0 ? NULL : sw.waits[w].text[0] ? sw.waits[w].text : swarm_fixed_text(sw.waits[w].stuck);
+}
+// Whose news the face already shows: the Lead in a Swarm, else the pane.
+static const char *face_id(void)
+{
+ if (swarm_mode()) return sw.lead[0] ? sw.lead : NULL;
+ return active() ? active()->id : NULL;
+}
+static void swarm_send(int op, const char *tab, const char *lead)
+{
+ action_t a = {.kind = A_SUPERTAB, .value = op};
+ COPY(a.text, tab); COPY(a.id, lead);
+ queue(a);
+}
+// The Lead at `i` comes onto the face: its recap is asked for afresh. `select` moves the desktop there too; a
+// supertab.focus does not need it, the desktop is already there.
+static void swarm_show(const ht_supertab_t *t, int i, bool select)
+{
+ if (!t || i < 0 || i >= t->lead_n) {
+ sw.lead[0] = 0; sw.at = 0;
+ ht_supertabs_recap_open(&swarm, "", "", ms());
+ return;
+ }
+ COPY(sw.lead, t->leads[i].id); sw.at = i; sw.retried = false;
+ ht_supertabs_recap_open(&swarm, t->id, sw.lead, ms());
+ if (select) swarm_send(SUPERTAB_SELECT, t->id, sw.lead);
+ swarm_send(SUPERTAB_OPEN, t->id, sw.lead);
+ swarm_send(SUPERTAB_RECAP_GET, t->id, sw.lead);
+ change();
+}
+static void swarm_leave(void)
+{
+ if (!swarm_mode()) return;
+ swarm_send(SUPERTAB_OPEN, sw.tab, "");
+ sw.tab[0] = sw.lead[0] = 0; sw.at = 0;
+ ht_supertabs_recap_open(&swarm, "", "", ms());
+ change();
+}
+static const char *swarm_remembered(const char *tab)
+{
+ for (int i = 0; i < HT_SUPERTABS_MAX; i++) if (!strcmp(sw.focus[i].tab, tab)) return sw.focus[i].lead;
+ return NULL;
+}
+// Entered locally, never with the desk tab's workspace handshake: the dial already holds the Swarm. The face opens on
+// `lead`, else the Lead the desktop last showed, else the first project.
+static void swarm_enter(const ht_supertab_t *t, const char *lead, bool select)
+{
+ if (!t) return;
+ if (swarm_mode() && strcmp(sw.tab, t->id)) swarm_leave();
+ if (workspace.phase != HT_WORKSPACE_IDLE) ht_workspace_cancel_request(&workspace);
+ s.loading = false;
+ COPY(sw.tab, t->id);
+ int i = swarm_lead_index(t, lead);
+ if (i < 0) i = swarm_lead_index(t, swarm_remembered(t->id));
+ swarm_show(t, i < 0 ? 0 : i, select);
+ view(HOME);
+}
+/*
+ * TABS lists the desk tabs, then every Swarm the desktop has not opened, in the `supertabs` order. A desk tab linked
+ * to a Swarm keeps its place and name and enters that Swarm; a Swarm whose desk tab is not listed counts as unopened.
+ */
+static bool swarm_unopened(const ht_supertab_t *t)
+{
+ return !t->tab[0] || workspace_index(t->tab) < 0;
+}
+static const ht_supertab_t *tab_swarm(int i)
+{
+ if (i < 0) return NULL;
+ if (i < s.tab_count) return ht_supertabs_for_desk(&swarm, s.tabs[i].id);
+ for (int k = 0, n = s.tab_count;; k++) {
+ const ht_supertab_t *t = ht_supertabs_at(&swarm, k);
+ if (!t) return NULL;
+ if (swarm_unopened(t) && n++ == i) return t;
+ }
+}
+static int tabs_total(void)
+{
+ int n = s.tab_count;
+ for (int k = 0; ht_supertabs_at(&swarm, k); k++) n += swarm_unopened(ht_supertabs_at(&swarm, k));
+ return n;
+}
+// The page of a desk tab or Swarm id, -1 when neither is listed.
+static int tab_index_of(const char *id)
+{
+ int i = workspace_index(id);
+ if (i >= 0 || !id || !*id) return i;
+ for (i = s.tab_count; i < tabs_total(); i++) if (!strcmp(tab_swarm(i)->id, id)) return i;
+ for (i = 0; i < s.tab_count; i++) {
+ const ht_supertab_t *t = tab_swarm(i);
+ if (t && !strcmp(t->id, id)) return i;
+ }
+ return -1;
+}
+static const char *tab_id_at(int i)
+{
+ return i >= 0 && i < s.tab_count ? s.tabs[i].id : tab_swarm(i) ? tab_swarm(i)->id : "";
+}
+static int swarm_notice(const char *lead);
+static void swarm_notice_drop(const char *lead);
+// TABS opens on the Swarm the dial is in, else on the desktop's tab.
+static int tab_index_here(void)
+{
+ return swarm_mode() ? tab_index_of(sw.tab) : workspace_index(s.selected_tab);
+}
static void tabs_open(void)
{
view(TABS);
if (s.view != TABS) return;
- ht_tab_carousel_reset(&tab_carousel, s.tab_count, workspace_index(s.selected_tab));
+ ht_tab_carousel_reset(&tab_carousel, tabs_total(), tab_index_here());
}
static void workspace_failed(const char *message)
{
@@ -617,7 +772,8 @@ static void tabs_sync(void)
{
if (s.view!=TABS || (s.touch_down && s.touch_cancelled)) return;
int index=ht_tab_carousel_index(&tab_carousel);
- if (index>=0 && index<s.tab_count) tab_request(s.tabs[index].id,true);
+ // A Swarm's page waits for Done: it is entered with no workspace handshake.
+ if (index>=0 && index<s.tab_count && !tab_swarm(index)) tab_request(s.tabs[index].id,true);
}
static int waiting(void)
{
@@ -1009,6 +1165,12 @@ static void surface_tick(uint32_t now)
change();
}
if (home_caption_tick(now)) change();
+ // A recap lost on the way is asked for once more after 5 s; the daemon ignores a repeat within 1 s.
+ if (swarm_mode() && swarm.recap.state == HT_RECAP_LOADING && !sw.retried &&
+ (int32_t)(now - swarm.recap.asked_ms) >= 5000) {
+ sw.retried = true;
+ swarm_send(SUPERTAB_RECAP_GET, swarm.recap.tab, swarm.recap.lead);
+ }
uint8_t phase = status_animated() ? ht_shimmer_phase(now * status_speed()) : 0;
if (phase != s.status_phase) { s.status_phase = phase; change(); }
// The voice screen's listening scene runs while the finger is down (hold-to-talk); the pets do not.
@@ -1121,11 +1283,77 @@ static void focus_bell(ht_scene_t *f, unsigned count, int bell_y)
HT_LV_BELL);
ht_text(f, x + BELL_PAD_H + bw + BELL_GAP, bell_y + (h - cf->height) / 2, cw, cf, ink, blue, text);
}
+static void render_focus_panes(ht_scene_t *f);
+/*
+ * A SWARM PANE'S FACE (spec §4): the agent face, built from the Lead. The project on the upper arc; working: the pet
+ * and the time since `since` (none for a remote Lead); asking or stuck: the asking pose and, in the recap's place, the
+ * local wait's question, else the Lead's last message; done: that message, or the resting face. No Leads: PANES' own
+ * "No panes in this tab.".
+ */
+static void render_swarm_face(ht_scene_t *f)
+{
+ const ht_lead_t *l = swarm_lead();
+ if (!l) { render_focus_panes(f); return; }
+ const char *wait = swarm_wait_text(l);
+ bool asking = l->state == HT_LEAD_ASK || l->state == HT_LEAD_STUCK || wait;
+ bool working = l->state == HT_LEAD_WORK && !wait;
+ const char *recap = wait ? wait : !working && swarm.recap.state == HT_RECAP_LOADED &&
+ !strcmp(swarm.recap.lead, l->id) && !s.nap ? swarm.recap.text : NULL;
+ uint32_t since_ms = working && l->since_s >= 0 ? (uint32_t)l->since_s * 1000u + (ms() - l->since_at_ms) : 0;
+ uint32_t since = since_ms / 1000;
+ s.timer_at = 0;
+ if (since) {
+ uint32_t next = fmt_elapsed_next_ms(since), frac = since_ms % 1000;
+ if (next > frac) { s.timer_at = ms() + next - frac; if (!s.timer_at) s.timer_at = 1; }
+ }
+ unsigned unread = notice_unread(l->id);
+ bool bell = unread > 0;
+ uint32_t clock = ms() | 1;
+ bool again = unread > s.bell_unread && s.bell_unread && s.notice_ms;
+ if (unread > s.bell_unread) s.notice_ms = clock;
+ s.bell_unread = unread;
+ const ht_supertab_t *t = swarm_here();
+ ht_character_face_t f_ = {.recipient = l->project[0] ? l->project : "Untitled", .status = "", .hint = "",
+ .tab = t ? t->name : "", .engine = l->engine, .activity = working && !s.nap ? "Working" : "",
+ .elapsed = since, .detail = "", .mood = character_mood(), .pose = character.motion.reaction.pose,
+ .asking = asking,
+ .clock_ms = (s.quiet || display_is_asleep()) ? 0 : clock,
+ .notice_ms = bell ? s.notice_ms : 0, .notices = bell ? (uint16_t)(unread > 65535 ? 65535 : unread) : 0,
+ .straight_title = s.straight_title, .ink = FG, .foreground = FG, .dim = DIM,
+ .primary_title = true, .roomy_reading = true};
+ bool focus_face = character.id == HT_CHARACTER_FOCUS;
+ if (focus_face) ht_focus_pick_working(&s.working_pick, &f_, recap, l->id, esp_random);
+ if (again && focus_face) {
+ s.notice_ms = (clock - ht_focus_alert_pop_ms(&f_)) | 1;
+ f_.notice_ms = bell ? s.notice_ms : 0;
+ }
+ ht_character_face(f, &character, &f_, ACCENT, recap);
+ s.pet_next_ms = focus_face ? ht_focus_pet_next_ms(&f_, recap) : 0;
+ ht_rect_t bubble = {0};
+ bool told = bell && focus_face && ht_focus_alert_shown(&f_, recap, &bubble);
+ int bell_y = 400;
+ if (bell && !told) {
+ if (focus_face) focus_bell(f, unread, bell_y);
+ else ht_notification_bell(f, unread, f_.ink);
+ }
+ // The same targets as a pane's face: the name opens PANES, the bell the inbox, the rest talks (to a local Lead).
+ s.hits[s.hit_count++] = (hit_t){{83, 0, 300, 66}, A_AGENTS, 0, true};
+ for (int i = 0; i < f->count; i++) if (f->runs[i].arc == 1) {
+ ht_rect_t r = ht_run_bounds(&f->runs[i]);
+ s.caption_arc = (ht_rect_t){r.x - 14, r.y - 14, r.w + 28, r.h + 28};
+ break;
+ }
+ if (bell && !told) s.hits[s.hit_count++] = (hit_t){{83, bell_y - 18, 300, 84}, A_INBOX, 0, true};
+ if (told && bubble.w) s.hits[s.hit_count++] = (hit_t){{bubble.x - 14, bubble.y - 14, bubble.w + 28, bubble.h + 28}, A_INBOX, 0, true};
+ s.hits[s.hit_count++] = focus_face ? (hit_t){{0, 66, HT_WIDTH, HT_HEIGHT - 66}, A_PET, 0, true}
+ : (hit_t){{33, 66, 400, 316}, A_PET, 0, true};
+}
static void render_home(ht_scene_t *f)
{
s.caption_arc = (ht_rect_t){0};
s.pet_next_ms = 0; s.timer_at = 0;
if (!s.connected || s.loading) { render_brand(f); return; }
+ if (swarm_mode()) { render_swarm_face(f); return; }
if (workspace.touching && workspace.moved && !workspace.cancelled) { render_workspace_preview(f); return; }
agent_t *a = active();
// The top caption belongs to the current pane; only completed work gets
@@ -1352,13 +1580,18 @@ static void focus_carousel(ht_scene_t *f, const ht_tab_carousel_t *c, int count,
action_kind_t pick); // with the tabs, below
static const char *pane_label(int i)
{
+ // In a Swarm the panes are its projects (decision 6: Leads only).
+ if (swarm_mode()) return swarm_here()->leads[i].project[0] ? swarm_here()->leads[i].project : "Untitled";
return s.agents[i].name[0] ? s.agents[i].name : "Untitled";
}
static void render_focus_panes(ht_scene_t *f)
{
uint16_t fg = color(0xeaeaf0), pressed_fill = color(0x30333f); // the Choose-a-tab pill's ink and press
focus_header(f, "PANES");
- if (!s.count) {
+ const ht_supertab_t *here = swarm_here();
+ int count = here ? here->lead_n : s.count, current = here ? sw.at : s.active;
+ action_kind_t pick = here ? A_LEAD : A_AGENT;
+ if (!count) {
/*
* NO PANES (design 2026-10-06, focus-project.html "Panes, none"): "No panes in / this tab." on two Inter 44
* lines 52 px apart, centred on the glass (181..285), and under it the door to the tab list, "Choose a tab":
@@ -1368,9 +1601,10 @@ static void render_focus_panes(ht_scene_t *f)
enum { LINE = 52, BUTTON_X = 103, BUTTON_Y = 333, BUTTON_W = 260, BUTTON_H = 64 };
const ht_font_t *big = &ht_lv_inter_44.base, *pf = &ht_lv_inter_28.base;
static const char *const empty[2] = {"No panes in", "this tab."};
- int lines = s.loading ? 1 : 2, top = 233 - lines * LINE / 2;
+ bool loading = s.loading && !here;
+ int lines = loading ? 1 : 2, top = 233 - lines * LINE / 2;
for (int n = 0; n < 2; n++) {
- const char *text = n >= lines ? "" : s.loading ? "Loading..." : empty[n];
+ const char *text = n >= lines ? "" : loading ? "Loading..." : empty[n];
int w = text[0] ? ht_measure(big, text) : 1;
ht_text(f, (HT_WIDTH - w) / 2, top + n * LINE + (LINE - big->height) / 2, w, big, FG, BG, text);
}
@@ -1384,12 +1618,12 @@ static void render_focus_panes(ht_scene_t *f)
}
// The panes as the tabs are paged (design 2026-10-06): the pane on the face is the one the pages open on; a pane
// that comes or goes keeps them in step. Done (green, at the foot) and a tap on the chosen page open it.
- if (pane_carousel.count != s.count)
- ht_tab_carousel_reset(&pane_carousel, s.count, s.active >= 0 && s.active < s.count ? s.active : 0);
- focus_carousel(f, &pane_carousel, s.count, pane_label, A_AGENT);
+ if (pane_carousel.count != count)
+ ht_tab_carousel_reset(&pane_carousel, count, current >= 0 && current < count ? current : 0);
+ focus_carousel(f, &pane_carousel, count, pane_label, pick);
ht_text(f, (HT_WIDTH - ht_done_28.width) / 2, 400, ht_done_28.width, &ht_done_28,
s.connected ? color(HT_THEME_VOICE) : DIM, BG, HT_DONE);
- s.hits[s.hit_count++] = (hit_t){{83, 392, 300, 74}, A_AGENT, ht_tab_carousel_index(&pane_carousel), s.connected};
+ s.hits[s.hit_count++] = (hit_t){{83, 392, 300, 74}, pick, ht_tab_carousel_index(&pane_carousel), s.connected};
}
static void render_agents(ht_scene_t *f)
{
@@ -1695,7 +1929,9 @@ static void focus_carousel(ht_scene_t *f, const ht_tab_carousel_t *c, int count,
}
static const char *tab_label(int i)
{
- return s.tabs[i].name[0] ? s.tabs[i].name : "Untitled";
+ // A Swarm's page is drawn as any tab's (decision 1): its name, nothing else.
+ const char *name = i < s.tab_count ? s.tabs[i].name : tab_swarm(i) ? tab_swarm(i)->name : "";
+ return name[0] ? name : "Untitled";
}
static void render_focus_tabs(ht_scene_t *f)
{
@@ -1704,7 +1940,7 @@ static void render_focus_tabs(ht_scene_t *f)
focus_centred(f, 214, 348, &ht_lv_inter_30.base, DIM, BG, "No tabs yet.");
return;
}
- focus_carousel(f, &tab_carousel, s.tab_count, tab_label, A_TAB);
+ focus_carousel(f, &tab_carousel, tabs_total(), tab_label, A_TAB);
}
static void render_tabs(ht_scene_t *f)
{
@@ -1823,6 +2059,13 @@ static void inbox_page(ht_scene_t *f, int i, int cx, uint8_t alpha)
char name[HT_TEXT_BYTES], machine[HT_TEXT_BYTES] = "";
if (n->machine[0]) ht_fit_width(machine, sizeof machine, n->machine, LINE_W, mid);
int a = find(n->agent_id), engine = a >= 0 ? ht_focus_engine_index(s.agents[a].engine) : -1;
+ if (a < 0 && n->swarm) {
+ // A Swarm entry's engine is its Lead's.
+ for (int k = 0; k < swarm.n && engine < 0; k++) {
+ int l = swarm_lead_index(&swarm.tabs[k], n->agent_id);
+ if (l >= 0) engine = ht_focus_engine_index(swarm.tabs[k].leads[l].engine);
+ }
+ }
int lead = engine >= 0 ? MARK : DOT;
ht_fit_width(name, sizeof name, n->name[0] ? n->name : n->agent_id, LINE_W - lead - MARK_GAP, mid);
int h = (machine[0] ? ROW + GAP : 0) + ROW + GAP + lines * PITCH, top = (HT_HEIGHT - h) / 2;
@@ -2313,8 +2556,10 @@ static action_t make_action(hit_t h)
COPY(a.id, s.agents[h.value].id);
else if (h.action == A_NOTICE && h.value < s.notice_count)
COPY(a.id, s.notice[h.value].agent_id);
- else if (h.action == A_TAB && h.value < s.tab_count)
- COPY(a.id, s.tabs[h.value].id);
+ else if (h.action == A_TAB && h.value < tabs_total())
+ COPY(a.id, tab_id_at(h.value));
+ else if (h.action == A_LEAD && swarm_here() && h.value < swarm_here()->lead_n)
+ COPY(a.id, swarm_here()->leads[h.value].id);
else if (h.action == A_MACHINE && h.value < s.machine_count)
COPY(a.id, s.machines[h.value].id);
else if (h.action == A_MODEL && h.value < s.model_count) {
@@ -2324,6 +2569,8 @@ static action_t make_action(hit_t h)
COPY(a.id,s.q.agent); a.dy=s.q.index;
} else if (h.action == A_DESKTOP && h.value == 1)
COPY(a.id, s.q.agent);
+ else if (swarm_mode())
+ COPY(a.id, swarm_lead() ? swarm_lead()->local : ""); // a remote Lead has none: nothing to talk to
else if (active())
COPY(a.id, active()->id);
return a;
@@ -2405,6 +2652,12 @@ static void draft_move(int delta, uint32_t now)
change();
}
}
+// The Lead a face voice turn goes to: the one on the face, when `id` is its local harness.
+static const ht_lead_t *voice_lead(const char *id, int value)
+{
+ const ht_lead_t *l = value == 0 || value == 1 ? swarm_lead() : NULL;
+ return l && l->local[0] && !strcmp(l->local, id) ? l : NULL;
+}
static void dispatch(action_t a)
{
#ifdef DEVICE_CREATURE_GALLERY
@@ -2446,6 +2699,7 @@ static void dispatch(action_t a)
break;
case A_AGENTS: {
view(AGENTS);
+ if (swarm_here()) { ht_tab_carousel_reset(&pane_carousel, swarm_here()->lead_n, sw.at); break; }
ht_tab_carousel_reset(&pane_carousel, s.count, s.active >= 0 && s.active < s.count ? s.active : 0);
int last = s.count > TAB_ROWS ? s.count - TAB_ROWS : 0;
s.offset = s.active - TAB_ROWS / 2;
@@ -2457,6 +2711,7 @@ static void dispatch(action_t a)
int i = find(a.id);
if (i < 0)
break;
+ swarm_leave();
if (visit.available && strcmp(visit.agent, a.id)) ht_visit_close(&visit);
s.active = i;
view(AGENT);
@@ -2464,6 +2719,12 @@ static void dispatch(action_t a)
queue(a);
break;
}
+ case A_LEAD: {
+ int i = swarm_lead_index(swarm_here(), a.id);
+ if (i >= 0 && i != sw.at) swarm_show(swarm_here(), i, true);
+ if (swarm_mode()) view(HOME);
+ break;
+ }
case A_READER:
view(READER);
break;
@@ -2499,6 +2760,16 @@ static void dispatch(action_t a)
notice_open();
break;
case A_NOTICE: {
+ if (s.connected && a.id[0] && swarm_notice(a.id) >= 0) {
+ // The dial's own entry: enter that Swarm at that Lead, read-only for a remote one (spec §5).
+ for (int i = 0; i < s.notice_count; i++)
+ if (!strcmp(s.notice[i].agent_id, a.id)) notice_mark_read(&s.notice[i]);
+ const ht_supertab_t *t = NULL;
+ for (int k = 0; k < swarm.n && !t; k++) if (swarm_lead_index(&swarm.tabs[k], a.id) >= 0) t = &swarm.tabs[k];
+ if (t) swarm_enter(t, a.id, true);
+ else swarm_notice_drop(a.id);
+ break;
+ }
if (s.connected && !visit.pending && a.id[0]) {
for (int i = 0; i < s.notice_count; i++)
if (!strcmp(s.notice[i].agent_id, a.id)) notice_mark_read(&s.notice[i]);
@@ -2559,14 +2830,27 @@ static void dispatch(action_t a)
case A_MACHINES:
view(MACHINES);
break;
- case A_TAB:
- if (s.view==TABS && workspace_index(a.id)>=0)
- ht_tab_carousel_reset(&tab_carousel,s.tab_count,workspace_index(a.id));
+ case A_TAB: {
+ int index = tab_index_of(a.id);
+ if (s.view==TABS && index>=0)
+ ht_tab_carousel_reset(&tab_carousel,tabs_total(),index);
+ const ht_supertab_t *t = tab_swarm(index);
+ if (t) {
+ if (s.view!=TABS) swarm_enter(t,NULL,true); // on TABS, Done enters it
+ break;
+ }
+ if (s.view!=TABS) swarm_leave();
tab_request(a.id,s.view==TABS);
break;
+ }
case A_TAB_DONE:
if (s.view!=TABS) break;
ht_tab_carousel_cancel(&tab_carousel);
+ if (tab_swarm(ht_tab_carousel_index(&tab_carousel))) {
+ swarm_enter(tab_swarm(ht_tab_carousel_index(&tab_carousel)),NULL,true);
+ break;
+ }
+ swarm_leave();
tabs_sync();
if (s.view!=TABS) break; // preserve a queue failure shown by tabs_sync
if (workspace.phase!=HT_WORKSPACE_IDLE) {
@@ -2633,13 +2917,15 @@ static void dispatch(action_t a)
s.nap = false;
s.voice_return = s.view;
int target = find(a.id);
+ const ht_lead_t *lead = voice_lead(a.id, a.value);
+ if (lead) target = -1;
if (a.value == 2) snprintf(s.voice_target, sizeof s.voice_target, "Find %.48s",
!strcmp(form.page.title, "Find Harness") ? "Harness" :
!strcmp(form.page.title, "New Harness") ? form.page.label : form.page.title);
else if (a.value == 7) COPY(s.voice_target, "Find in output");
else if (a.value == 5 || a.value == 6) COPY(s.voice_target, draft.page.name);
- else COPY(s.voice_target, target >= 0 ? s.agents[target].name : "harness");
- COPY(s.voice_engine, target >= 0 && a.value != 2 && a.value != 5 && a.value != 6 && a.value != 7 ?
+ else COPY(s.voice_target, lead ? lead->project : target >= 0 ? s.agents[target].name : "harness");
+ COPY(s.voice_engine, lead ? lead->engine : target >= 0 && a.value != 2 && a.value != 5 && a.value != 6 && a.value != 7 ?
s.agents[target].engine : "");
s.voice_started = ms();
view(VOICE);
@@ -2758,7 +3044,12 @@ static void dispatch(action_t a)
view(STOP);
break;
case A_STOP_YES:
- if (s.connected && find(s.stop_agent) >= 0 && s.agents[find(s.stop_agent)].busy) {
+ if (s.connected && swarm_lead() && swarm_lead()->local[0] && !strcmp(swarm_lead()->local, s.stop_agent) &&
+ swarm_lead()->state == HT_LEAD_WORK) {
+ COPY(a.id, s.stop_agent);
+ queue(a);
+ view(HOME);
+ } else if (s.connected && find(s.stop_agent) >= 0 && s.agents[find(s.stop_agent)].busy) {
COPY(a.id, s.stop_agent);
queue(a);
view(AGENT);
@@ -2802,6 +3093,7 @@ static void dispatch(action_t a)
break;
case A_SETTINGS_SAVE:
break; // the worker's alone: it is queued, never dispatched from a hit rect
+ case A_SUPERTAB:
case A_QUESTION_READ:
case A_NOTICE_READ:
case A_TAB_REFRESH:
@@ -2863,6 +3155,11 @@ static void worker(void *unused)
case A_DESKTOP:
cable_client_send_open(a.id, NULL);
break;
+ case A_SUPERTAB: {
+ static const char *ops[] = {"supertab.recap.get", "supertab.open", "supertab.select"};
+ if (a.value >= SUPERTAB_RECAP_GET && a.value <= SUPERTAB_SELECT) cable_client_supertab_send(ops[a.value], a.text, a.id);
+ break;
+ }
case A_NOTICE_READ:
cable_client_notification_read(a.id, a.text);
break;
@@ -3026,7 +3323,7 @@ void habitat_touch(bool down, int x, int y, uint32_t now)
if (surface && pressed_action.kind==A_TABS && !s.touch_brake)
ht_workspace_touch(&workspace,workspace_index(s.selected_tab),s.tab_count,x,y,now);
if (s.view == TABS && pressed_action.kind == A_TAB) ht_tab_carousel_begin(&tab_carousel, x, now);
- if (s.view == AGENTS && character.id == HT_CHARACTER_FOCUS && pressed_action.kind == A_AGENT)
+ if (s.view == AGENTS && character.id == HT_CHARACTER_FOCUS && (pressed_action.kind == A_AGENT || pressed_action.kind == A_LEAD))
ht_tab_carousel_begin(&pane_carousel, x, now);
if (s.view == INBOX && character.id == HT_CHARACTER_FOCUS && pressed_action.kind == A_NOTICE)
ht_tab_carousel_begin(&inbox_carousel, x, now);
@@ -3100,7 +3397,7 @@ void habitat_touch(bool down, int x, int y, uint32_t now)
} else if (tab_contact) {
int index = pressed_action.value;
if (tab_tap && result == HT_TOUCH_TAP && pressed_action.kind == A_TAB && index >= 0 &&
- index < s.tab_count && !strcmp(pressed_action.id, s.tabs[index].id)) {
+ index < tabs_total() && !strcmp(pressed_action.id, tab_id_at(index))) {
dispatch(pressed_action);
// On Focus a tap on a name is the check too (owner, 2026-10-06), as on the panes.
if (character.id == HT_CHARACTER_FOCUS && s.view == TABS) dispatch((action_t){.kind = A_TAB_DONE});
@@ -3121,6 +3418,8 @@ void habitat_touch(bool down, int x, int y, uint32_t now)
int index = pressed_action.value;
if (pane_tap && result == HT_TOUCH_TAP && pressed_action.kind == A_AGENT && index >= 0 &&
index < s.count && !strcmp(pressed_action.id, s.agents[index].id)) dispatch(pressed_action);
+ if (pane_tap && result == HT_TOUCH_TAP && pressed_action.kind == A_LEAD && swarm_here() && index >= 0 &&
+ index < swarm_here()->lead_n && !strcmp(pressed_action.id, swarm_here()->leads[index].id)) dispatch(pressed_action);
change();
} else if (result == HT_TOUCH_TAP && s.touch_brake) {
// DOWN already stopped desktop inertia. This entire tap is only a brake.
@@ -3166,7 +3465,7 @@ void habitat_touch(bool down, int x, int y, uint32_t now)
* and let go before the 650 ms that opens the tabs.
*/
ht_gesture_guard(&gesture, now);
- if (s.connected && !s.loading && active()) {
+ if (s.connected && !s.loading && (active() || swarm_mode())) {
ESP_LOGI("habitat", "focus touch: start voice");
// Built as the old microphone's was: make_action names the agent on the face, and
// main-surface voice without a recipient is dropped.
@@ -3211,7 +3510,7 @@ void habitat_touch(bool down, int x, int y, uint32_t now)
// Reading/choosing consumed this contact; motion cannot submit an answer.
} else if (s.view == SELECTION) {
// Its bounded reading cursor already consumed this vertical drag.
- } else if (surface && character.id == HT_CHARACTER_FOCUS && dy > 0 && notice_unread(active() ? active()->id : NULL)) {
+ } else if (surface && character.id == HT_CHARACTER_FOCUS && dy > 0 && notice_unread(face_id())) {
// Pull down from the badge. The creature skins keep this drag inert — their footer
// badge is a target you tap — but on Focus the badge sits at the top edge and a pull
// is the gesture the rest of the world already means by it.
@@ -3249,7 +3548,13 @@ void habitat_touch(bool down, int x, int y, uint32_t now)
if (dx>0 && !s.q.pending) view(s.view==ANSWER_REVIEW ? CHOICE : s.view==CHOICE ? QUESTION : HOME);
} else if (s.view == INBOX && s.notice_count)
s.offset = (s.offset + (dx < 0 ? 1 : s.notice_count - 1)) % s.notice_count;
- else if (surface && s.count && s.connected && !s.loading) {
+ else if (surface && swarm_here() && swarm_here()->lead_n && s.connected) {
+ // A Swarm's next or previous project, by `order`, wrapping as the panes do (never `focus`).
+ int n = swarm_here()->lead_n;
+ swarm_show(swarm_here(), (sw.at + (dx < 0 ? 1 : n - 1)) % n, true);
+ } else if (surface && swarm_mode()) {
+ // A Swarm with no projects has nowhere to swipe to.
+ } else if (surface && s.count && s.connected && !s.loading) {
int i = s.active < 0 ? 0 : (s.active + (dx < 0 ? 1 : s.count - 1)) % s.count;
action_t a = {.kind = A_AGENT};
COPY(a.id, s.agents[i].id);
@@ -3291,6 +3596,11 @@ uint32_t habitat_next_wake_ms(void)
if (s.view == INBOX && inbox_carousel.animating && !display_is_asleep()) delay = 16;
if (selection.pending && delay > 100) delay = 100;
if (visit.pending && delay > 100) delay = 100;
+ if (swarm_mode() && swarm.recap.state == HT_RECAP_LOADING && !sw.retried) {
+ int32_t left = (int32_t)(swarm.recap.asked_ms + 5000 - now);
+ uint32_t due = left < 1 ? 1 : (uint32_t)left;
+ if (due < delay) delay = due;
+ }
if (s.view == FORM && delay > 100) delay = 100;
if (character.motion.next_ms && character.motion.next_ms < delay) delay = character.motion.next_ms;
if (home_caption_rotates() && home_caption.next_ms && home_caption.next_ms < delay)
@@ -4213,6 +4523,7 @@ static void notice_expire(uint32_t now)
// The pane whose face is on the glass already shows its own news.
static bool on_face(const char *id)
{
+ if (swarm_mode()) return sw.lead[0] && !strcmp(sw.lead, id) && (s.view == HOME || s.view == AGENT) && !s.nap && !display_is_asleep();
const agent_t *a = active();
return a && !strcmp(a->id, id) && (s.view == HOME || s.view == AGENT) && !s.nap && !display_is_asleep();
}
@@ -4314,6 +4625,10 @@ void ui_notif_replace(const cable_notif_t *rows, int count)
held = s.notice[s.offset];
if (!rows || count < 0) count = 0;
if (count > NOTICES) count = NOTICES;
+ // The desktop's snapshot replaces its own rows only: the dial's Swarm entries go back in after it, first.
+ static EXT_RAM_BSS_ATTR cable_notif_t own[NOTICES]; // static: off the reader task's stack
+ int own_count = 0;
+ for (int i = 0; i < s.notice_count; i++) if (s.notice[i].swarm) own[own_count++] = s.notice[i];
s.notice_count = 0;
for (int i = count - 1; i >= 0; i--) {
notice_add(rows[i].agent_id, rows[i].name, rows[i].machine, rows[i].summary,
@@ -4333,6 +4648,14 @@ void ui_notif_replace(const cable_notif_t *rows, int count)
!strcmp(rows[j].read_token, s.notice_reads[i].token)) present = true;
if (!present) s.notice_reads[i].pending = false;
}
+ for (int i = own_count - 1; i >= 0; i--) {
+ notice_add(own[i].agent_id, own[i].name, own[i].machine, own[i].summary, true, false);
+ for (int j = 0; j < s.notice_count; j++) if (!strcmp(s.notice[j].agent_id, own[i].agent_id)) {
+ s.notice[j].swarm = own[i].swarm; s.notice[j].read_on_dial = own[i].read_on_dial;
+ s.notice[j].received_ms = own[i].received_ms;
+ break;
+ }
+ }
bool retained = false;
for (int i = 0; i < s.notice_count; i++) if (!strcmp(s.notice[i].agent_id, selected)) retained = true;
if (held.agent_id[0] && !retained && s.notice_count < NOTICES) {
@@ -4481,17 +4804,24 @@ void ui_service_model_picker(void)
}
display_unlock();
}
-void ui_swarms_replace(const cable_swarm_t *rows, int count, const char *selected)
+// The last `swarms` list as it came, so a Swarm's link arriving later can still list its desk tab.
+static EXT_RAM_BSS_ATTR cable_swarm_t desk_rows[SWARMS_MAX];
+static int desk_row_count;
+static char desk_selected[ID_MAX];
+static void swarms_apply(void)
{
- // A tab with no agent (only shells or viewers, or nothing) is not listed: nothing on the dial can drive it.
+ // A tab with no agent (only shells or viewers, or nothing) is not listed: nothing on the dial can drive it. A
+ // Swarm's desk tab is, whatever it counts: its project's Lead may run on another machine.
static cable_swarm_t shown[SWARMS_MAX]; // static: too large for the reader task's stack; single writer
- int total=!rows || count<0 ? 0 : count>SWARMS_MAX ? SWARMS_MAX : count, bounded=0;
- for (int i=0;i<total;i++) if (rows[i].agents>0) shown[bounded++]=rows[i];
- rows=shown;
- display_lock();
+ int bounded=0;
+ for (int i=0;i<desk_row_count;i++)
+ if (desk_rows[i].agents>0 || ht_supertabs_for_desk(&swarm,desk_rows[i].id)) shown[bounded++]=desk_rows[i];
+ const cable_swarm_t *rows=shown;
+ const char *selected=desk_selected;
char focused[ID_MAX] = "";
int focused_index = ht_tab_carousel_index(&tab_carousel);
- if (s.view == TABS && focused_index >= 0 && focused_index < s.tab_count) COPY(focused, s.tabs[focused_index].id);
+ if (s.view == TABS && focused_index >= 0) COPY(focused, tab_id_at(focused_index));
+ int total_before = tabs_total();
bool selected_changed=strcmp(s.selected_tab,selected ? selected : "");
bool browsing=workspace.phase!=HT_WORKSPACE_IDLE || tab_carousel.touching || tab_carousel.animating;
bool changed=bounded!=s.tab_count;
@@ -4502,9 +4832,10 @@ void ui_swarms_replace(const cable_swarm_t *rows, int count, const char *selecte
s.tab_count=bounded;
if (bounded) memcpy(s.tabs,rows,(size_t)bounded*sizeof *rows);
COPY(s.selected_tab,selected);
+ changed = changed || total_before != tabs_total();
if (s.view == TABS && (changed || (selected_changed && !browsing))) {
- int index = browsing ? workspace_index(focused) : workspace_index(s.selected_tab);
- ht_tab_carousel_reset(&tab_carousel, bounded, index >= 0 ? index : workspace_index(s.selected_tab));
+ int index = browsing ? tab_index_of(focused) : tab_index_here();
+ ht_tab_carousel_reset(&tab_carousel, tabs_total(), index >= 0 ? index : tab_index_here());
}
if (workspace.phase!=HT_WORKSPACE_IDLE && workspace_index(workspace.pending)<0) {
workspace_failed("That workspace is gone. Choose another.");
@@ -4514,7 +4845,218 @@ void ui_swarms_replace(const cable_swarm_t *rows, int count, const char *selecte
if (!queue((action_t){.kind=A_TAB_REFRESH,.revision=workspace.serial}))
workspace_failed("Device busy. Choose the tab again.");
}
- change(); display_unlock();
+ change();
+}
+void ui_swarms_replace(const cable_swarm_t *rows, int count, const char *selected)
+{
+ display_lock();
+ desk_row_count=!rows || count<0 ? 0 : count>SWARMS_MAX ? SWARMS_MAX : count;
+ if (desk_row_count) memcpy(desk_rows,rows,(size_t)desk_row_count*sizeof *rows);
+ COPY(desk_selected,selected);
+ swarms_apply();
+ display_unlock();
+}
+/*
+ * A LEAD THAT NEEDS YOU (spec §5): one question-type inbox entry per Lead, keyed by its id and marked as the dial's own
+ * (`swarm`: 1 needs you, 2 stuck) so the desktop's snapshot does not drop it. It beeps when it is new or changes kind,
+ * so a wait and a state change, in either order, beep once. The text is the local wait's question when one is open,
+ * else the approved fixed line; the grey line is the Swarm's name.
+ */
+static void utf8_trim(char *text)
+{
+ // A name cut to its field may end inside a letter; drop the broken tail.
+ size_t n = strlen(text), k = n;
+ while (k && ((uint8_t)text[k - 1] & 0xc0) == 0x80) k--;
+ if (!k) return;
+ uint8_t lead = (uint8_t)text[k - 1];
+ size_t want = lead >= 0xf0 ? 4 : lead >= 0xe0 ? 3 : lead >= 0xc0 ? 2 : 1;
+ if (n - (k - 1) < want) text[k - 1] = 0;
+}
+static int swarm_notice(const char *lead)
+{
+ for (int i = 0; i < s.notice_count; i++) if (s.notice[i].swarm && !strcmp(s.notice[i].agent_id, lead)) return i;
+ return -1;
+}
+// notice_add files a plain entry; this marks it as the dial's own.
+static void swarm_notice_mark(const char *lead, uint8_t kind)
+{
+ for (int i = 0; i < s.notice_count; i++) if (!strcmp(s.notice[i].agent_id, lead)) {
+ s.notice[i].swarm = kind;
+ utf8_trim(s.notice[i].name); utf8_trim(s.notice[i].machine);
+ return;
+ }
+}
+static bool swarm_notice_raise(const ht_supertab_t *t, const ht_lead_t *l, bool stuck)
+{
+ uint8_t kind = stuck ? 2 : 1;
+ int i = swarm_notice(l->id), w = swarm_wait_of(l->local);
+ bool fresh = i < 0 || s.notice[i].swarm != kind;
+ if (fresh) notice_forget_read(l->id);
+ notice_add(l->id, l->project[0] ? l->project : "Untitled", w >= 0 && sw.waits[w].swarm[0] ? sw.waits[w].swarm : t->name,
+ w >= 0 ? swarm_wait_text(l) : swarm_fixed_text(stuck), true, false);
+ swarm_notice_mark(l->id, kind);
+ if (w >= 0) sw.waits[w].shown = true;
+ s.notice_sequence++;
+ bool face = on_face(l->id);
+ if (face) notice_read_now(l->id);
+ else if (fresh) display_wake();
+ change();
+ return fresh && !face;
+}
+static void swarm_notice_drop(const char *lead)
+{
+ if (swarm_notice(lead) < 0) return;
+ notice_remove(lead, true);
+ notice_sync_view();
+ change();
+}
+static bool swarm_events(const ht_lead_event_t *ev, int n)
+{
+ bool beep = false;
+ for (int k = 0; k < n; k++) {
+ const ht_supertab_t *t = ht_supertabs_find(&swarm, ev[k].tab);
+ int i = swarm_lead_index(t, ev[k].lead);
+ if (ev[k].kind == HT_LEAD_CLEARED || i < 0) swarm_notice_drop(ev[k].lead);
+ else beep |= swarm_notice_raise(t, &t->leads[i], ev[k].kind == HT_LEAD_RAISED_STUCK);
+ }
+ return beep;
+}
+// TABS follows the list when it is open, on the page it was showing.
+static void swarm_tabs_changed(void)
+{
+ if (s.view != TABS || tab_carousel.count == tabs_total()) return;
+ char focused[ID_MAX];
+ COPY(focused, tab_id_at(ht_tab_carousel_index(&tab_carousel)));
+ input_cancel();
+ int index = tab_index_of(focused);
+ ht_tab_carousel_reset(&tab_carousel, tabs_total(), index >= 0 ? index : tab_index_here());
+}
+void ui_supertabs_ids(const char ids[][ID_MAX], int n)
+{
+ static EXT_RAM_BSS_ATTR ht_lead_event_t ev[HT_SUPERTABS_MAX * HT_SUPERTAB_LEADS_MAX]; // static: off the reader task's stack
+ display_lock();
+ int count = ht_supertabs_ids(&swarm, ids, n, ev, (int)(sizeof ev / sizeof ev[0]));
+ swarm_events(ev, count);
+ if (swarm_mode() && !swarm_here()) {
+ // The Swarm on the face is gone: back to the list.
+ sw.tab[0] = sw.lead[0] = 0;
+ ht_supertabs_recap_open(&swarm, "", "", ms());
+ if (s.view == HOME || s.view == AGENT || s.view == AGENTS) tabs_open();
+ }
+ swarms_apply();
+ swarm_tabs_changed();
+ change();
+ display_unlock();
+}
+bool ui_supertab(const ht_supertab_t *in)
+{
+ static EXT_RAM_BSS_ATTR ht_lead_event_t ev[HT_SUPERTAB_LEADS_MAX * 2];
+ if (!in) return false;
+ display_lock();
+ bool linked = in->tab[0] && !ht_supertabs_for_desk(&swarm, in->tab);
+ int n = ht_supertabs_put(&swarm, in, ms(), ev, (int)(sizeof ev / sizeof ev[0]));
+ bool beep = swarm_events(ev, n);
+ // A wait that came before any Lead named its harness shows now, once.
+ for (int w = 0; w < SWARM_WAITS; w++) {
+ const ht_supertab_t *t = NULL;
+ const ht_lead_t *l = sw.waits[w].agent[0] && !sw.waits[w].shown ?
+ ht_supertabs_lead_by_local(&swarm, sw.waits[w].agent, &t) : NULL;
+ if (l) beep |= swarm_notice_raise(t, l, sw.waits[w].stuck);
+ }
+ const ht_supertab_t *t = swarm_here();
+ if (t && !strcmp(t->id, in->id)) {
+ // The face keeps its Lead; a Lead that went leaves the face on the one now at its place.
+ int i = swarm_lead_index(t, sw.lead);
+ if (i >= 0) sw.at = i;
+ else if (t->lead_n) swarm_show(t, sw.at < t->lead_n ? sw.at : t->lead_n - 1, false);
+ else swarm_show(t, -1, false);
+ }
+ if (linked) swarms_apply();
+ swarm_tabs_changed();
+ change();
+ display_unlock();
+ return beep;
+}
+void ui_supertab_recap(const char *tab, const char *lead, const char *text, uint32_t at, bool none)
+{
+ display_lock();
+ if (ht_supertabs_recap_put(&swarm, tab, lead, text, at, none)) change();
+ display_unlock();
+}
+void ui_supertab_focus(const char *tab, const char *lead)
+{
+ if (!tab || !lead) return;
+ display_lock();
+ int slot = -1;
+ for (int i = 0; i < HT_SUPERTABS_MAX && slot < 0; i++) if (!strcmp(sw.focus[i].tab, tab)) slot = i;
+ for (int i = 0; i < HT_SUPERTABS_MAX && slot < 0; i++) if (!sw.focus[i].tab[0] || !ht_supertabs_find(&swarm, sw.focus[i].tab)) slot = i;
+ if (slot >= 0) { COPY(sw.focus[slot].tab, tab); COPY(sw.focus[slot].lead, lead); }
+ const ht_supertab_t *t = ht_supertabs_find(&swarm, tab);
+ int i = swarm_lead_index(t, lead);
+ // As `focus` today: never while talking, nor over a question or a form.
+ bool free = !s.voice_open && !question_view(s.view) && s.view != FORM && s.view != DRAFT && s.view != DRAFT_OPTIONS;
+ if (i >= 0 && free) {
+ if (swarm_mode() && !strcmp(sw.tab, tab)) {
+ if (strcmp(sw.lead, lead)) swarm_show(t, i, false);
+ } else if (!swarm_mode() && t->tab[0] && !strcmp(s.selected_tab, t->tab) && (s.view == HOME || s.view == AGENT)) {
+ swarm_enter(t, lead, false); // the desktop opened this Swarm's tab: the dial goes in with it
+ }
+ }
+ change();
+ display_unlock();
+}
+bool ui_supertab_wait(const char *agent_id, const char *request, const char *swarm_name, bool stuck, const char *text)
+{
+ if (!agent_id || !agent_id[0] || strlen(agent_id) >= ID_MAX || !request) return false;
+ display_lock();
+ int w = swarm_wait_of(agent_id);
+ for (int i = 0; i < SWARM_WAITS && w < 0; i++) if (!sw.waits[i].agent[0]) w = i;
+ if (w < 0) w = 0; // ponytail: sixteen open waits on one machine; the oldest slot gives way
+ bool same = !strcmp(sw.waits[w].agent, agent_id) && sw.waits[w].shown;
+ memset(&sw.waits[w], 0, sizeof sw.waits[w]);
+ COPY(sw.waits[w].agent, agent_id); COPY(sw.waits[w].request, request);
+ COPY(sw.waits[w].swarm, swarm_name); utf8_trim(sw.waits[w].swarm);
+ recap_preview(sw.waits[w].text, sizeof sw.waits[w].text, text);
+ sw.waits[w].stuck = stuck;
+ sw.waits[w].shown = same;
+ const ht_supertab_t *t = NULL;
+ const ht_lead_t *l = ht_supertabs_lead_by_local(&swarm, agent_id, &t);
+ bool beep = l && swarm_notice_raise(t, l, stuck);
+ change();
+ display_unlock();
+ return beep;
+}
+void ui_supertab_wait_close(const char *agent_id, const char *request)
+{
+ display_lock();
+ int w = swarm_wait_of(agent_id);
+ if (w >= 0 && request && !strcmp(sw.waits[w].request, request)) {
+ memset(&sw.waits[w], 0, sizeof sw.waits[w]);
+ const ht_supertab_t *t = NULL;
+ const ht_lead_t *l = ht_supertabs_lead_by_local(&swarm, agent_id, &t);
+ // Still asking: back to the fixed line, with no second beep. Otherwise the entry goes.
+ if (l && (l->state == HT_LEAD_ASK || l->state == HT_LEAD_STUCK) && swarm_notice(l->id) >= 0) {
+ int i = swarm_notice(l->id);
+ uint8_t kind = s.notice[i].swarm;
+ notice_add(l->id, l->project[0] ? l->project : "Untitled", t->name, swarm_fixed_text(kind == 2), true, false);
+ swarm_notice_mark(l->id, kind);
+ if (on_face(l->id)) notice_read_now(l->id);
+ } else if (l) swarm_notice_drop(l->id);
+ change();
+ }
+ display_unlock();
+}
+void ui_supertabs_clear(void)
+{
+ display_lock();
+ for (int i = s.notice_count - 1; i >= 0; i--) if (s.notice[i].swarm) notice_remove(s.notice[i].agent_id, true);
+ notice_sync_view();
+ ht_supertabs_reset(&swarm);
+ memset(&sw, 0, sizeof sw);
+ swarms_apply();
+ swarm_tabs_changed();
+ change();
+ display_unlock();
}
void ui_show_machines(void)
{
@@ -5113,6 +5655,13 @@ void ui_boot_pressed(void)
display_lock();
if (s.voice_open || audio_client_active()) {
dispatch((action_t){.kind = A_VOICE_ABORT});
+ } else if (swarm_mode()) {
+ // Only a Lead on this computer can be stopped from here; a remote one goes home.
+ const ht_lead_t *l = swarm_lead();
+ if ((s.view == HOME || s.view == AGENT) && l && l->local[0] && l->state == HT_LEAD_WORK) {
+ COPY(s.stop_agent, l->local);
+ view(STOP);
+ } else view(HOME);
} else if (s.view == AGENT && active() && active()->busy) {
COPY(s.stop_agent, active()->id);
view(STOP);
diff --git a/devices/harness-device/firmware/main/ui/habitat/workspace.c b/devices/harness-device/firmware/main/ui/habitat/workspace.c
index 44d486c1e..5dae877b0 100644
--- a/devices/harness-device/firmware/main/ui/habitat/workspace.c
+++ b/devices/harness-device/firmware/main/ui/habitat/workspace.c
@@ -82,7 +82,7 @@ int ht_tab_carousel_index(const ht_tab_carousel_t *c)
}
void ht_tab_carousel_reset(ht_tab_carousel_t *c, int count, int index)
{
- count = bounded(count, 0, 24);
+ count = bounded(count, 0, HT_TAB_PAGES_MAX);
*c = (ht_tab_carousel_t){.count=count};
c->position = c->target = count ? bounded(index, 0, count - 1) * HT_TAB_PITCH : 0;
}
diff --git a/devices/harness-device/firmware/main/ui/habitat/workspace.h b/devices/harness-device/firmware/main/ui/habitat/workspace.h
index 737631271..e363543d6 100644
--- a/devices/harness-device/firmware/main/ui/habitat/workspace.h
+++ b/devices/harness-device/firmware/main/ui/habitat/workspace.h
@@ -28,7 +28,8 @@ bool ht_workspace_tick(ht_workspace_t *, uint32_t now);
// Thumb-driven tab pages. Position is in glass pixels; all easing is integer.
// The UI sends the centered tab as it changes, including during drag and settling.
// The return from end only identifies a settled tap; Done closes the picker.
-enum { HT_TAB_PITCH = 228, HT_TAB_DRAG_GAIN = 2, HT_TAB_SETTLE_MS = 192 };
+// At most 40 pages: the desktop's 24 tabs and 16 Swarms it has not opened.
+enum { HT_TAB_PITCH = 228, HT_TAB_DRAG_GAIN = 2, HT_TAB_SETTLE_MS = 192, HT_TAB_PAGES_MAX = 40 };
typedef struct {
int count, position, from, target, origin, x, last_x, velocity;
uint32_t began, sampled, animation_at;
diff --git a/devices/harness-device/firmware/main/ui/ui_screens.h b/devices/harness-device/firmware/main/ui/ui_screens.h
index 4b3612cde..9ade27a37 100644
--- a/devices/harness-device/firmware/main/ui/ui_screens.h
+++ b/devices/harness-device/firmware/main/ui/ui_screens.h
@@ -12,6 +12,7 @@
#include "config_store.h"
#include "../cable_machines.h" // cable_machine_t — the wheel's row, already parsed and diffed
#include "../cable_client.h" // cable_swarm_t — one of the window's tabs, as the wire carries it
+#include "habitat/supertab.h" // ht_supertab_t — one Swarm and its Leads, as cable_client parsed it
struct cJSON;
@@ -251,6 +252,20 @@ void ui_machines_refresh(void);
// Replace the whole list from one `swarms` frame. `selected` names the one the window has on screen; it
// is what every tile's swarm line draws. count 0 hides the line. Safe from the reader task.
void ui_swarms_replace(const cable_swarm_t *rows, int count, const char *selected);
+
+// --- The Swarms (Super Tabs; cable_client.h). Each is safe from the reader task. ---
+// The `supertabs` list: the Swarms shown, in order. A Swarm gone from it leaves the list and the inbox.
+void ui_supertabs_ids(const char ids[][ID_MAX], int n);
+// One Swarm's card. True when the caller should beep: a Lead started needing a person, off the face.
+bool ui_supertab(const ht_supertab_t *in);
+void ui_supertab_recap(const char *tab, const char *lead, const char *text, uint32_t at, bool none);
+void ui_supertab_focus(const char *tab, const char *lead);
+// A Super Tab wait from harness `agent_id` (some Lead's `local`). It only sets that Lead's inbox text and face;
+// it never opens the question screen. True when the caller should beep.
+bool ui_supertab_wait(const char *agent_id, const char *request, const char *swarm_name, bool stuck, const char *text);
+void ui_supertab_wait_close(const char *agent_id, const char *request);
+// Link lost: forget every Swarm and its inbox entries.
+void ui_supertabs_clear(void);
/* The grid of the tab named by `swarm_id`, as the window laid it out.
*
* THE ID IS NOT DECORATION. These rectangles describe the APP's active tab, and this device can be
diff --git a/devices/harness-device/firmware/test/run.sh b/devices/harness-device/firmware/test/run.sh
index 28003c37e..2d5c082e2 100644
--- a/devices/harness-device/firmware/test/run.sh
+++ b/devices/harness-device/firmware/test/run.sh
@@ -126,6 +126,10 @@ cc -std=c11 -Wall -Wextra -Werror -O1 -g -fsanitize="${SANITIZERS:-undefined,bou
-o "$out/test_workspace" "$here/test_workspace.c" "$here/../main/ui/habitat/workspace.c"
"$out/test_workspace"
+cc -std=c11 -Wall -Wextra -Werror -O1 -g -fsanitize="${SANITIZERS:-undefined,bounds}" \
+ -o "$out/test_supertab" "$here/test_supertab.c" "$here/../main/ui/habitat/supertab.c"
+"$out/test_supertab"
+
cc -std=c11 -Wall -Wextra -Werror -O1 -g -fsanitize="${SANITIZERS:-undefined,bounds}" \
-o "$out/test_tim" "$here/test_tim.c" "$here/../main/ui/habitat/tim.c" "$here/../main/ui/habitat/character_motion.c" "$here/../main/ui/habitat/character_layout.c" \
"$here/../main/ui/habitat/terminal.c" "$here/../main/ui/habitat/fonts.c"
@@ -246,6 +250,7 @@ if [[ -n "${IDF_PATH:-}" ]]; then
python3 "$here/test_cable_json_parse.py"
python3 "$here/test_companion_protocol.py"
python3 "$here/test_cable_identity.py"
+ python3 "$here/test_cable_supertab.py"
python3 "$here/test_cable_models.py"
python3 "$here/test_cable_outbound.py"
fi
diff --git a/devices/harness-device/firmware/test/test_cable_supertab.py b/devices/harness-device/firmware/test/test_cable_supertab.py
new file mode 100644
index 000000000..5b729e5dc
--- /dev/null
+++ b/devices/harness-device/firmware/test/test_cable_supertab.py
@@ -0,0 +1,203 @@
+"""The Swarm frames on the round dial: hello, supertabs/supertab/recap/focus, Super Tab waits and the three requests.
+
+The production handlers are lifted out of cable_client.c and run against the SDK's cJSON and the real supertab model.
+Requires IDF_PATH.
+"""
+from pathlib import Path
+import os
+import re
+import subprocess
+import tempfile
+from native_shapes import MAIN, defines
+
+source = Path(os.environ.get('CABLE_SOURCE', MAIN/'cable_client.c')).read_text()
+json_dir = Path(os.environ['IDF_PATH'])/'components/json/cJSON'
+
+
+def function(name):
+ match = re.search(r'^[^\n]*\b'+name+r'\([^;]*?\)\n\{.*?^\}', source, re.M | re.S)
+ assert match, name
+ return match[0]+'\n'
+
+
+code = r'''
+#include "cJSON.h"
+#include "ui/habitat/supertab.h"
+#include <assert.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#define EXT_RAM_BSS_ATTR
+#define ESP_LOGI(...) ((void)0)
+#define CABLE_PRODUCT "harness"
+#define CABLE_PROTO_VERSION 3
+#define PET_STORE_MAX_PACKS 4
+'''
+code += defines('CABLE_READ_TOKEN_MAX')
+code += r'''
+static char wire[4][2048];
+static int sends;
+static bool send_json(cJSON *root) {
+ if (!root) return false;
+ char *text=cJSON_PrintUnformatted(root);cJSON_Delete(root);assert(text&&strlen(text)<sizeof wire[0]);
+ snprintf(wire[sends++%4],sizeof wire[0],"%s",text);cJSON_free(text);return true;
+}
+typedef struct { const char *name; } board_t;
+static const board_t *board(void) { static const board_t b={"dial-stub"};return &b; }
+static const char *cable_fw_version(void) { return "0.0.99"; }
+static bool device_mac_str(char *o,size_t n) { snprintf(o,n,"aa:bb");return true; }
+static void msg_settings(cJSON **root) { (void)root; }
+static size_t pet_store_held(char ids[][17],size_t max) { (void)ids;(void)max;return 0; }
+
+static unsigned beeps, ids_calls, card_calls, recap_calls, focus_calls, wait_calls, close_calls, question_calls, qclose_calls;
+static bool beep_next;
+static void audio_notify_done(void) { beeps++; }
+static char got_ids[HT_SUPERTABS_MAX][ID_MAX]; static int got_id_n;
+static ht_supertab_t got_card;
+static char got_tab[ID_MAX], got_lead[ID_MAX], got_text[2048], got_agent[ID_MAX], got_request[80], got_swarm[80];
+static uint32_t got_at; static bool got_none, got_stuck, got_text_null;
+static void ui_supertabs_ids(const char ids[][ID_MAX],int n) {
+ ids_calls++;got_id_n=n;memcpy(got_ids,ids,(size_t)n*ID_MAX);
+}
+static bool ui_supertab(const ht_supertab_t *in) { card_calls++;got_card=*in;return beep_next; }
+static void ui_supertab_recap(const char *tab,const char *lead,const char *text,uint32_t at,bool none) {
+ recap_calls++;snprintf(got_tab,sizeof got_tab,"%s",tab);snprintf(got_lead,sizeof got_lead,"%s",lead);
+ snprintf(got_text,sizeof got_text,"%s",text?text:"");got_at=at;got_none=none;
+}
+static void ui_supertab_focus(const char *tab,const char *lead) {
+ focus_calls++;snprintf(got_tab,sizeof got_tab,"%s",tab);snprintf(got_lead,sizeof got_lead,"%s",lead);
+}
+static bool ui_supertab_wait(const char *agent,const char *request,const char *swarm,bool stuck,const char *text) {
+ wait_calls++;snprintf(got_agent,sizeof got_agent,"%s",agent);snprintf(got_request,sizeof got_request,"%s",request);
+ snprintf(got_swarm,sizeof got_swarm,"%s",swarm);got_stuck=stuck;got_text_null=!text;
+ snprintf(got_text,sizeof got_text,"%s",text?text:"");return beep_next;
+}
+static void ui_supertab_wait_close(const char *agent,const char *request) {
+ close_calls++;snprintf(got_agent,sizeof got_agent,"%s",agent);snprintf(got_request,sizeof got_request,"%s",request);
+}
+static bool ui_question_show(const char *a,const char *n,const char *m,const char *r,const cJSON *q) {
+ (void)a;(void)n;(void)m;(void)r;(void)q;question_calls++;return beep_next;
+}
+static void ui_question_close(const char *a,const char *r) { (void)a;(void)r;qclose_calls++; }
+'''
+for name in ['str_of', 'msg', 'msg_check', 'msg_string', 'msg_number', 'msg_array', 'send_hello', 'id_fits',
+ 'handle_supertabs', 'handle_supertab', 'handle_supertab_recap', 'handle_supertab_focus',
+ 'handle_question', 'handle_question_close', 'cable_client_supertab_send']:
+ code += function(name)
+code += r'''
+static cJSON *parse(const char *json) { cJSON *p=cJSON_Parse(json);assert(p);return p; }
+static void feed(void (*handler)(const cJSON *),const char *json) { cJSON *p=parse(json);handler(p);cJSON_Delete(p); }
+static void feed_agent(void (*handler)(const cJSON *,const char *),const char *json) {
+ cJSON *p=parse(json);handler(p,str_of(p,"agentId"));cJSON_Delete(p);
+}
+static const char *field(const char *json,const char *key) {
+ static char out[256];cJSON *p=parse(json);const char *v=str_of(p,key);
+ snprintf(out,sizeof out,"%s",v?v:"<absent>");cJSON_Delete(p);return out;
+}
+
+int main(void) {
+ // The hello names both capabilities, so the daemon sends the Swarm cards and Super Tab waits.
+ send_hello();
+ assert(sends==1 && !strcmp(field(wire[0],"swarmCard"),"v1") && !strcmp(field(wire[0],"superTab"),"wait-v1"));
+ assert(!strcmp(field(wire[0],"product"),"harness"));
+
+ // supertabs: ids in order, the bad and the repeated skipped, at most 16.
+ feed(handle_supertabs,"{\"ids\":[\"s1\",\"\",7,\"s2\",\"s1\",\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"]}");
+ assert(ids_calls==1 && got_id_n==2 && !strcmp(got_ids[0],"s1") && !strcmp(got_ids[1],"s2"));
+ feed(handle_supertabs,"{\"ids\":\"s1\"}");
+ assert(ids_calls==1); // not a list: the current set stays
+ feed(handle_supertabs,"{\"ids\":[]}");
+ assert(ids_calls==2 && got_id_n==0);
+
+ // supertab: every field, `order` and an absent `since`; a malformed Lead is skipped, not the frame.
+ feed(handle_supertab,"{\"id\":\"s1\",\"tab\":\"desk-7\",\"name\":\"openharness\",\"count\":4,\"leads\":["
+ "{\"id\":\"L1\",\"projectId\":\"p1\",\"project\":\"mobile\",\"engine\":\"claude\",\"owner\":\"Ann\",\"local\":\"h1\",\"state\":\"work\",\"since\":134,\"order\":2},"
+ "{\"projectId\":\"no-id\",\"state\":\"ask\"},"
+ "\"not an object\","
+ "{\"id\":\"L2\",\"project\":\"web\",\"engine\":\"codex\",\"local\":\"\",\"state\":\"ask\",\"order\":0},"
+ "{\"id\":\"L1\",\"project\":\"again\",\"state\":\"stuck\"},"
+ "{\"id\":\"L3\",\"project\":\"api\",\"state\":\"bogus\",\"since\":-5,\"order\":-1}]}");
+ assert(card_calls==1 && !strcmp(got_card.id,"s1") && !strcmp(got_card.tab,"desk-7") && !strcmp(got_card.name,"openharness"));
+ assert(got_card.count==4 && got_card.lead_n==3 && beeps==0);
+ const ht_lead_t *l=&got_card.leads[0];
+ assert(!strcmp(l->id,"L1") && !strcmp(l->project_id,"p1") && !strcmp(l->project,"mobile") && !strcmp(l->engine,"claude"));
+ assert(!strcmp(l->owner,"Ann") && !strcmp(l->local,"h1") && l->state==HT_LEAD_WORK && l->since_s==134 && l->order==2);
+ l=&got_card.leads[1];
+ assert(!strcmp(l->id,"L2") && l->state==HT_LEAD_ASK && l->since_s<0 && l->order==0 && !l->local[0]);
+ l=&got_card.leads[2];
+ assert(!strcmp(l->id,"L3") && l->state==HT_LEAD_DONE && l->since_s<0 && l->order==-1);
+ // No count: the Leads listed. No id: no frame. An overlong tab links to nothing.
+ feed(handle_supertab,"{\"id\":\"s2\",\"tab\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"name\":\"x\",\"leads\":[{\"id\":\"L1\",\"state\":\"work\"}]}");
+ assert(card_calls==2 && got_card.count==1 && !got_card.tab[0]);
+ feed(handle_supertab,"{\"name\":\"x\",\"leads\":[]}");
+ assert(card_calls==2);
+ // 13 Leads: 12 kept. The model's raised events come back as one beep.
+ char big[4096]="{\"id\":\"s1\",\"name\":\"n\",\"leads\":[";
+ for (int i=0;i<13;i++) { char one[64];snprintf(one,sizeof one,"%s{\"id\":\"L%d\",\"state\":\"work\",\"order\":%d}",i?",":"",i,i);strcat(big,one); }
+ strcat(big,"]}");
+ beep_next=true;feed(handle_supertab,big);beep_next=false;
+ assert(card_calls==3 && got_card.lead_n==12 && got_card.count==12 && beeps==1);
+
+ // supertab.recap and supertab.focus.
+ feed(handle_supertab_recap,"{\"tab\":\"s1\",\"lead\":\"L1\",\"text\":\"Shipped.\",\"at\":1792560000,\"none\":false}");
+ assert(recap_calls==1 && !strcmp(got_text,"Shipped.") && got_at==1792560000u && !got_none && !strcmp(got_lead,"L1"));
+ feed(handle_supertab_recap,"{\"tab\":\"s1\",\"lead\":\"L1\",\"none\":true}");
+ assert(recap_calls==2 && got_none && !got_text[0] && got_at==0);
+ feed(handle_supertab_recap,"{\"tab\":\"s1\",\"text\":\"x\"}");
+ assert(recap_calls==2);
+ feed(handle_supertab_focus,"{\"tab\":\"s1\",\"lead\":\"L2\"}");
+ assert(focus_calls==1 && !strcmp(got_tab,"s1") && !strcmp(got_lead,"L2"));
+ feed(handle_supertab_focus,"{\"tab\":\"s1\"}");
+ assert(focus_calls==1);
+
+ // A Super Tab wait goes to ui_supertab_wait, never to the question screen, and beeps only when the UI says so.
+ feed_agent(handle_question,"{\"agentId\":\"h1\",\"name\":\"Lead\",\"id\":\"supertab:a1\",\"questions\":[{\"q\":\"Ship it?\"}],"
+ "\"superTab\":\"openharness\",\"attention\":\"decision\"}");
+ assert(wait_calls==1 && question_calls==0 && beeps==1 && !strcmp(got_agent,"h1") && !strcmp(got_request,"supertab:a1"));
+ assert(!strcmp(got_swarm,"openharness") && !got_stuck && !strcmp(got_text,"Ship it?"));
+ beep_next=true;
+ feed_agent(handle_question,"{\"agentId\":\"h1\",\"id\":\"supertab:a2\",\"questions\":[],\"superTab\":\"openharness\",\"attention\":\"stuck\"}");
+ assert(wait_calls==2 && question_calls==0 && beeps==2 && got_stuck && got_text_null);
+ // A plain question is unchanged.
+ feed_agent(handle_question,"{\"agentId\":\"h1\",\"id\":\"r1\",\"questions\":[{\"q\":\"Pick\"}]}");
+ assert(question_calls==1 && wait_calls==2 && beeps==3);
+ feed_agent(handle_question,"{\"agentId\":\"h1\",\"id\":\"r1\",\"questions\":[{\"q\":\"Pick\"}],\"superTab\":\"\"}");
+ assert(question_calls==2 && wait_calls==2);
+ beep_next=false;
+ feed_agent(handle_question,"{\"id\":\"supertab:a3\",\"superTab\":\"openharness\"}");
+ assert(wait_calls==2); // no agent: nothing to attach it to
+ // question.close: a Super Tab one closes the wait, any other the question screen.
+ feed_agent(handle_question_close,"{\"agentId\":\"h1\",\"id\":\"supertab:a1\"}");
+ assert(close_calls==1 && qclose_calls==0 && !strcmp(got_request,"supertab:a1"));
+ feed_agent(handle_question_close,"{\"agentId\":\"h1\",\"id\":\"r1\"}");
+ assert(close_calls==1 && qclose_calls==1);
+
+ // The three requests, exactly.
+ sends=0;
+ cable_client_supertab_send("supertab.recap.get","s1","L1");
+ cable_client_supertab_send("supertab.open","s1","");
+ cable_client_supertab_send("supertab.select","s1","L2");
+ assert(sends==3);
+ assert(!strcmp(wire[0],"{\"t\":\"supertab.recap.get\",\"tab\":\"s1\",\"lead\":\"L1\"}"));
+ assert(!strcmp(wire[1],"{\"t\":\"supertab.open\",\"tab\":\"s1\",\"lead\":\"\"}"));
+ assert(!strcmp(wire[2],"{\"t\":\"supertab.select\",\"tab\":\"s1\",\"lead\":\"L2\"}"));
+ char longer[ID_MAX+1];memset(longer,'x',ID_MAX);longer[ID_MAX]=0;
+ cable_client_supertab_send("supertab.recap.get","s1","");
+ cable_client_supertab_send("supertab.select","s1",NULL);
+ cable_client_supertab_send("supertab.open","","L1");
+ cable_client_supertab_send("supertab.open",longer,"L1");
+ cable_client_supertab_send("supertab.open","s1",longer);
+ cable_client_supertab_send("focus","s1","L1");
+ cable_client_supertab_send(NULL,"s1","L1");
+ assert(sends==3);
+ puts("Swarm frames: hello capabilities, supertabs/supertab/recap/focus parsing, malformed Leads skipped, Super Tab waits kept off the question screen, exact requests PASS");
+}
+'''
+with tempfile.TemporaryDirectory(prefix='harness-supertab-') as folder:
+ out=Path(folder);(out/'test.c').write_text(code)
+ subprocess.run(['cc','-std=c11','-Wall','-Wextra','-Werror','-Wno-deprecated-declarations','-Wno-unused-function','-O1','-g',
+ '-fsanitize='+os.environ.get('SANITIZERS','undefined,bounds'),'-I',str(json_dir),'-I',str(MAIN),
+ str(out/'test.c'),str(MAIN/'ui/habitat/supertab.c'),str(json_dir/'cJSON.c'),'-o',str(out/'test')],check=True)
+ subprocess.run([str(out/'test')],check=True)
diff --git a/devices/harness-device/firmware/test/test_supertab.c b/devices/harness-device/firmware/test/test_supertab.c
new file mode 100644
index 000000000..efea7f7c6
--- /dev/null
+++ b/devices/harness-device/firmware/test/test_supertab.c
@@ -0,0 +1,202 @@
+#include "../main/ui/habitat/supertab.h"
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static ht_supertabs_t model; // 54 KB: never on the stack, as on the board
+
+static ht_lead_in_t lead(const char *id, const char *state, int order)
+{
+ return (ht_lead_in_t){.id=id, .project_id="p", .project=id, .engine="claude", .owner="", .local="",
+ .state=state, .order=order, .since=-1};
+}
+static void frame(ht_supertab_t *t, const char *id, int n, const char *const *states, const int *orders)
+{
+ assert(ht_supertab_init(t, id, "", id, n));
+ for (int i = 0; i < n; i++) {
+ char lid[16]; snprintf(lid, sizeof lid, "L%d", i);
+ ht_lead_in_t in = lead(lid, states[i], orders ? orders[i] : -1);
+ assert(ht_supertab_lead_add(t, &in));
+ }
+}
+
+static void order_and_limits(void)
+{
+ static ht_supertab_t t;
+ ht_supertabs_reset(&model);
+ const char ids[2][ID_MAX] = {"s1", "s2"};
+ ht_supertabs_ids(&model, ids, 2, NULL, 0);
+ const char *st[4] = {"done", "work", "ask", "stuck"};
+ int orders[4] = {2, 0, 2, 1};
+ frame(&t, "s1", 4, st, orders);
+ ht_supertabs_put(&model, &t, 0, NULL, 0);
+ const ht_supertab_t *r = ht_supertabs_find(&model, "s1");
+ assert(r && r->lead_n == 4);
+ // By order, ties stable: L1(0) L3(1) L0(2) L2(2).
+ assert(!strcmp(r->leads[0].id, "L1") && !strcmp(r->leads[1].id, "L3"));
+ assert(!strcmp(r->leads[2].id, "L0") && !strcmp(r->leads[3].id, "L2"));
+ assert(r->leads[0].state == HT_LEAD_WORK && r->leads[1].state == HT_LEAD_STUCK);
+ // A daemon without `order`: frame order.
+ frame(&t, "s2", 4, st, NULL);
+ ht_supertabs_put(&model, &t, 0, NULL, 0);
+ r = ht_supertabs_find(&model, "s2");
+ for (int i = 0; i < 4; i++) { char lid[4]; snprintf(lid, sizeof lid, "L%d", i); assert(!strcmp(r->leads[i].id, lid)); }
+
+ // 13 in, 12 kept.
+ assert(ht_supertab_init(&t, "s1", "", "s1", 13));
+ for (int i = 0; i < 13; i++) {
+ char lid[8]; snprintf(lid, sizeof lid, "L%d", i);
+ ht_lead_in_t in = lead(lid, "work", i);
+ assert(ht_supertab_lead_add(&t, &in) == (i < HT_SUPERTAB_LEADS_MAX));
+ }
+ assert(t.lead_n == 12 && t.count == 13);
+ // A name over 48 bytes is cut on a UTF-8 boundary: 47 ASCII bytes then "é" (2 bytes) leaves 47.
+ char name[64]; memset(name, 'a', 47); strcpy(name + 47, "\xc3\xa9tail");
+ assert(ht_supertab_init(&t, "s1", "", name, 1));
+ assert(strlen(t.name) == 47 && t.name[46] == 'a');
+ memset(name, 'b', 46); strcpy(name + 46, "\xc3\xa9tail"); // fits exactly at 48
+ assert(ht_supertab_init(&t, "s1", "", name, 1) && strlen(t.name) == 48);
+ // An id of ID_MAX bytes or more is rejected, for the Swarm and for a Lead; a Lead without one too.
+ char long_id[ID_MAX + 1]; memset(long_id, 'x', ID_MAX); long_id[ID_MAX] = 0;
+ assert(!ht_supertab_init(&t, long_id, "", "n", 1));
+ assert(!ht_supertab_init(&t, "s1", long_id, "n", 1));
+ long_id[ID_MAX - 1] = 0; assert(ht_supertab_init(&t, long_id, "", "n", 1));
+ assert(ht_supertab_init(&t, "s1", "", "n", 3));
+ ht_lead_in_t bad = lead(long_id, "work", 0); long_id[ID_MAX - 1] = 'x';
+ assert(!ht_supertab_lead_add(&t, &bad));
+ bad = lead("", "work", 0); assert(!ht_supertab_lead_add(&t, &bad));
+ bad = lead(NULL, "work", 0); assert(!ht_supertab_lead_add(&t, &bad));
+ bad = lead("L0", "work", 0); assert(ht_supertab_lead_add(&t, &bad) && !ht_supertab_lead_add(&t, &bad));
+ assert(ht_supertab_init(&t, "s1", "", "n", 3));
+ bad = lead("L9", NULL, 0); bad.project = NULL; bad.local = NULL; // optional fields may be absent
+ assert(ht_supertab_lead_add(&t, &bad) && t.lead_n == 1);
+ // Unknown state reads as done; `since` absent stays absent.
+ assert(t.leads[0].state == HT_LEAD_DONE && t.leads[0].since_s < 0 && !t.leads[0].project[0]);
+ bad = lead("L8", "thinking", 0); bad.since = 134;
+ assert(ht_supertab_lead_add(&t, &bad) && t.leads[1].state == HT_LEAD_DONE && t.leads[1].since_s == 134);
+
+ // A put for an id not in the last list is dropped; a list without a Swarm drops its record.
+ frame(&t, "s3", 4, st, NULL);
+ assert(ht_supertabs_put(&model, &t, 0, NULL, 0) == 0 && !ht_supertabs_find(&model, "s3"));
+ const char one[1][ID_MAX] = {"s2"};
+ ht_supertabs_ids(&model, one, 1, NULL, 0);
+ assert(!ht_supertabs_find(&model, "s1") && ht_supertabs_find(&model, "s2") && model.n == 1);
+ // 16 Swarms at most.
+ char many[17][ID_MAX];
+ for (int i = 0; i < 17; i++) snprintf(many[i], ID_MAX, "m%d", i);
+ ht_supertabs_ids(&model, (const char (*)[ID_MAX])many, 17, NULL, 0);
+ assert(model.id_n == HT_SUPERTABS_MAX && !ht_supertabs_find(&model, "s2"));
+ puts("supertab: order (stable, frame order without it), caps, UTF-8 cut, ids, unknown state PASS");
+}
+
+static int events(const ht_lead_event_t *ev, int n, ht_lead_event_kind_t kind, const char *lead_id)
+{
+ int c = 0;
+ for (int i = 0; i < n; i++) if (ev[i].kind == kind && !strcmp(ev[i].lead, lead_id) && !strcmp(ev[i].tab, "s1")) c++;
+ return c;
+}
+
+static void transitions(void)
+{
+ static ht_supertab_t t;
+ ht_lead_event_t ev[32];
+ ht_supertabs_reset(&model);
+ const char ids[1][ID_MAX] = {"s1"};
+ ht_supertabs_ids(&model, ids, 1, NULL, 0);
+ // First seen: ask raises, done/work do not.
+ const char *a[3] = {"done", "ask", "work"};
+ frame(&t, "s1", 3, a, NULL);
+ int n = ht_supertabs_put(&model, &t, 0, ev, 32);
+ assert(n == 1 && events(ev, n, HT_LEAD_RAISED_ASK, "L1") == 1);
+ // DONE→ASK raises ask once; ASK→ASK raises nothing.
+ const char *b[3] = {"ask", "ask", "work"};
+ frame(&t, "s1", 3, b, NULL);
+ n = ht_supertabs_put(&model, &t, 0, ev, 32);
+ assert(n == 1 && events(ev, n, HT_LEAD_RAISED_ASK, "L0") == 1);
+ n = ht_supertabs_put(&model, &t, 0, ev, 32);
+ assert(n == 0);
+ // ASK→STUCK raises stuck; STUCK→WORK clears.
+ const char *c[3] = {"stuck", "ask", "work"};
+ frame(&t, "s1", 3, c, NULL);
+ n = ht_supertabs_put(&model, &t, 0, ev, 32);
+ assert(n == 1 && events(ev, n, HT_LEAD_RAISED_STUCK, "L0") == 1);
+ const char *d[3] = {"work", "ask", "work"};
+ frame(&t, "s1", 3, d, NULL);
+ n = ht_supertabs_put(&model, &t, 0, ev, 32);
+ assert(n == 1 && events(ev, n, HT_LEAD_CLEARED, "L0") == 1);
+ // A Lead gone from the frame clears (L1 was asking); a quiet Lead leaving says nothing.
+ const char *e[1] = {"work"};
+ frame(&t, "s1", 1, e, NULL);
+ n = ht_supertabs_put(&model, &t, 0, ev, 32);
+ assert(n == 1 && events(ev, n, HT_LEAD_CLEARED, "L1") == 1);
+ // A Swarm leaving the list clears its asking Leads.
+ frame(&t, "s1", 2, b, NULL);
+ n = ht_supertabs_put(&model, &t, 0, ev, 32);
+ assert(n == 2);
+ n = ht_supertabs_ids(&model, ids, 0, ev, 32);
+ assert(n == 2 && events(ev, n, HT_LEAD_CLEARED, "L0") == 1 && events(ev, n, HT_LEAD_CLEARED, "L1") == 1);
+ // The event buffer is never overrun.
+ ht_supertabs_ids(&model, ids, 1, NULL, 0);
+ frame(&t, "s1", 2, b, NULL);
+ assert(ht_supertabs_put(&model, &t, 0, ev, 1) == 1);
+ // since is held with the dial clock at receipt.
+ assert(ht_supertab_init(&t, "s1", "", "s1", 1));
+ ht_lead_in_t w = lead("L0", "work", 0); w.since = 134;
+ assert(ht_supertab_lead_add(&t, &w));
+ ht_supertabs_put(&model, &t, 5000, NULL, 0);
+ const ht_lead_t *l = &ht_supertabs_find(&model, "s1")->leads[0];
+ assert(l->since_s == 134 && l->since_at_ms == 5000);
+ puts("supertab: raise once, ask->stuck, clear on work/gone/swarm gone, bounded events PASS");
+}
+
+static void lookups_and_recap(void)
+{
+ static ht_supertab_t t;
+ ht_supertabs_reset(&model);
+ const char ids[2][ID_MAX] = {"s1", "s2"};
+ ht_supertabs_ids(&model, ids, 2, NULL, 0);
+ assert(ht_supertab_init(&t, "s1", "desk-7", "openharness", 2));
+ ht_lead_in_t a = lead("L0", "work", 0); a.local = "h-local";
+ ht_lead_in_t b = lead("L1", "work", 1);
+ assert(ht_supertab_lead_add(&t, &a) && ht_supertab_lead_add(&t, &b));
+ ht_supertabs_put(&model, &t, 0, NULL, 0);
+ assert(ht_supertab_init(&t, "s2", "", "mobile", 0));
+ ht_supertabs_put(&model, &t, 0, NULL, 0);
+ assert(ht_supertabs_for_desk(&model, "desk-7") == ht_supertabs_find(&model, "s1"));
+ assert(!ht_supertabs_for_desk(&model, "") && !ht_supertabs_for_desk(&model, "desk-8"));
+ const ht_supertab_t *in = NULL;
+ const ht_lead_t *l = ht_supertabs_lead_by_local(&model, "h-local", &in);
+ assert(l && !strcmp(l->id, "L0") && in == ht_supertabs_find(&model, "s1"));
+ assert(!ht_supertabs_lead_by_local(&model, "", &in) && !ht_supertabs_lead_by_local(&model, NULL, &in));
+ // `at` walks the list order, skipping Swarms whose frame has not come.
+ assert(ht_supertabs_at(&model, 0) == ht_supertabs_find(&model, "s1"));
+ assert(ht_supertabs_at(&model, 1) == ht_supertabs_find(&model, "s2") && !ht_supertabs_at(&model, 2));
+
+ // Recap: only the open Lead's text lands.
+ ht_supertabs_recap_open(&model, "s1", "L0", 100);
+ assert(model.recap.state == HT_RECAP_LOADING && model.recap.asked_ms == 100 && !model.recap.text[0]);
+ assert(!ht_supertabs_recap_put(&model, "s1", "L1", "other", 1, false));
+ assert(model.recap.state == HT_RECAP_LOADING && !model.recap.text[0]);
+ char *big = malloc(1601); memset(big, 'r', 1599); strcpy(big + 1499, "\xe2\x80\xa6"); memset(big + 1502, 'r', 98); big[1600] = 0;
+ assert(ht_supertabs_recap_put(&model, "s1", "L0", big, 1792560000u, false));
+ assert(model.recap.state == HT_RECAP_LOADED && strlen(model.recap.text) == 1499 && model.recap.at == 1792560000u);
+ free(big);
+ ht_supertabs_recap_open(&model, "s1", "L1", 200);
+ assert(model.recap.state == HT_RECAP_LOADING && !model.recap.text[0]);
+ assert(ht_supertabs_recap_put(&model, "s1", "L1", "", 0, true) && model.recap.state == HT_RECAP_EMPTY);
+ ht_supertabs_recap_open(&model, "", "", 300);
+ assert(model.recap.state == HT_RECAP_NONE && !ht_supertabs_recap_put(&model, "", "", "x", 0, false));
+ ht_supertabs_recap_open(&model, "s1", "L0", 400);
+ ht_supertabs_reset(&model);
+ assert(model.n == 0 && model.id_n == 0 && model.recap.state == HT_RECAP_NONE && !model.recap.lead[0]);
+ puts("supertab: desk link, local Lead, list order, recap slot (one Lead, UTF-8 cut, none), reset PASS");
+}
+
+int main(void)
+{
+ order_and_limits();
+ transitions();
+ lookups_and_recap();
+ return 0;
+}
diff --git a/devices/harness-device/firmware/test/test_touch_ui.py b/devices/harness-device/firmware/test/test_touch_ui.py
index 741184234..8df0f0eff 100644
--- a/devices/harness-device/firmware/test/test_touch_ui.py
+++ b/devices/harness-device/firmware/test/test_touch_ui.py
@@ -34,6 +34,7 @@ code = r'''
#include "focus_faces.h"
#include "pets.h"
#include "workspace.h"
+#include "supertab.h"
#include "command_face.h"
#include "arc_geometry.inc"
#include <assert.h>
@@ -72,7 +73,7 @@ static struct {
uint32_t timer_at;
cable_swarm_t tabs[SWARMS_MAX];
struct { char id[64], name[96], state[16]; bool local; } machines[2];
- char selected_tab[ID_MAX], pending_focus[ID_MAX], opening_notice[ID_MAX], title[80], message[256];
+ char selected_tab[ID_MAX], pending_focus[ID_MAX], opening_notice[ID_MAX], title[80], message[256], stop_agent[ID_MAX];
cable_notif_t notice[NOTICES];
notice_receipt_t notice_reads[NOTICES];
uint8_t notice_read_next;
@@ -189,6 +190,7 @@ static bool carry_emit(const ht_carry_command_t *c, void *ctx) {
return true;
}
static uint32_t fake_ms;
+static char swarm_wire[64][128], stopped_agent[64]; static int swarm_sent;
static uint32_t ms(void) { return fake_ms ? fake_ms : gesture.began+75; }
static uint32_t fake_random; // even: the chef, odd: the builder (focus.c ht_focus_pick_working)
static uint32_t esp_random(void) { return fake_random; }
@@ -199,6 +201,11 @@ static bool queue(action_t a) {
if (a.kind==A_TAB_REFRESH) tab_queued=a;
if (a.kind==A_NOTICE_READ) { notice_reads_sent++; notice_read_queued=a; }
if (a.kind==A_DESKTOP) { desktop_opens++; COPY(opened_agent,a.id); }
+ if (a.kind==A_SUPERTAB && swarm_sent<64) {
+ static const char *ops[]={"recap.get","open","select"};
+ snprintf(swarm_wire[swarm_sent++],sizeof swarm_wire[0],"%s %s %s",ops[a.value],a.text,a.id);
+ }
+ if (a.kind==A_STOP_YES) COPY(stopped_agent,a.id);
return true;
}
static bool scroll_emit(ht_scroll_phase_t phase, int dy, int velocity, void *ctx) {
@@ -214,12 +221,22 @@ code += function('color')
code += function('settings_item') + function('settings_count') + function('hit_contains')
code += function('find')
code += 'static void notice_expire(uint32_t now);\n'
-for name in ['copy', 'recap_preview', 'notice_unread', 'notice_was_read', 'notice_forget_read', 'notice_flush_reads', 'notice_mark_read', 'habitat_scene_receipt', 'habitat_scene_presented', 'pane_memory', 'pane_memory_apply', 'dismiss_result', 'activity_text', 'ensure', 'input_cancel', 'view', 'notice_open', 'workspace_index', 'tabs_open', 'workspace_failed', 'tab_request', 'tabs_sync', 'ui_scroll_reportable', 'focus_skin', 'focus_face_for', 'focus_chord', 'focus_put', 'focus_span', 'focus_take', 'focus_rows', 'ui_rows', 'ui_can_display', 'ui_wrap', 'text_in', 'control', 'home_footer', 'footer_control', 'text', 'center', 'render_brand', 'heading', 'question_view', 'question_rows', 'question_move', 'question_text', 'render_question', 'render_choices', 'render_answer_review', 'question_answer', 'send_answer', 'make_action', 'character_mood', 'voice_status', 'home_caption_rotates', 'home_caption_tick', 'status_animated', 'status_speed', 'status_wake_ms', 'surface_tick', 'command_face', 'render_workspace_preview', 'question_prompt', 'focus_bell', 'render_home', 'render_voice', 'render_selection', 'render_form', 'draft_move', 'render_draft', 'render_draft_options', 'ui_swarms_replace', 'ui_workspace_applied', 'ui_land_after_reload']:
- code += function(name)
+swarm_core = source[source.index('/*\n * THE SWARMS'):source.index('static void tabs_open(void)')]
+swarm_parts = {
+ 'swarm_core': swarm_core,
+ 'render_swarm_face': 'static void render_focus_panes(ht_scene_t *f);\n' + function('render_swarm_face'),
+ # with the last `swarms` list it keeps beside it
+ 'swarms_apply': source[source.index('// The last `swarms` list as it came'):source.index('void ui_swarms_replace(')],
+}
+for name in ['copy', 'recap_preview', 'notice_unread', 'notice_was_read', 'notice_forget_read', 'notice_flush_reads', 'notice_mark_read', 'habitat_scene_receipt', 'habitat_scene_presented', 'pane_memory', 'pane_memory_apply', 'dismiss_result', 'activity_text', 'ensure', 'input_cancel', 'view', 'notice_open', 'workspace_index', 'swarm_core', 'voice_lead', 'tabs_open', 'workspace_failed', 'tab_request', 'tabs_sync', 'ui_scroll_reportable', 'focus_skin', 'focus_face_for', 'focus_chord', 'focus_put', 'focus_span', 'focus_take', 'focus_rows', 'ui_rows', 'ui_can_display', 'ui_wrap', 'text_in', 'control', 'home_footer', 'footer_control', 'text', 'center', 'render_brand', 'heading', 'question_view', 'question_rows', 'question_move', 'question_text', 'render_question', 'render_choices', 'render_answer_review', 'question_answer', 'send_answer', 'make_action', 'character_mood', 'voice_status', 'home_caption_rotates', 'home_caption_tick', 'status_animated', 'status_speed', 'status_wake_ms', 'surface_tick', 'command_face', 'render_workspace_preview', 'question_prompt', 'focus_bell', 'render_swarm_face', 'render_home', 'render_voice', 'render_selection', 'render_form', 'draft_move', 'render_draft', 'render_draft_options', 'swarms_apply', 'ui_swarms_replace', 'ui_workspace_applied', 'ui_land_after_reload']:
+ code += swarm_parts[name] if name in swarm_parts else function(name)
code += function('render_settings') + function('ui_visit_state')
code += function('ui_project_known') + function('ui_focus_project') + function('ui_apply_pending_focus')
code += function('focus_centred') + function('focus_header') + function('focus_clipped') + function('tabs_move') + function('tab_name') + function('tab_split') + function('tab_fade') + function('tab_neighbour') + function('focus_carousel') + function('tab_label') + function('render_focus_tabs') + function('pane_label') + function('render_focus_panes') + function('render_agents') + function('render_tabs') + function('page_controls') + function('render_notice') + function('css_line') + function('inbox_line') + function('inbox_page') + function('render_focus_inbox') + function('render_list')
-for name in ['notice_remove', 'notice_sync_view', 'notice_selection', 'notice_restore_selection', 'notice_add', 'notice_expire', 'on_face', 'notice_read_now', 'ui_notify_summary', 'ui_turn_error', 'ui_notif_seen', 'ui_notif_read', 'ui_notif_replace', 'ui_notif_open', 'ui_question_close', 'ui_answer_receipt']:
+for name in ['notice_remove', 'notice_sync_view', 'notice_selection', 'notice_restore_selection', 'notice_add', 'notice_expire', 'on_face', 'notice_read_now', 'ui_notify_summary', 'ui_turn_error', 'ui_notif_seen', 'ui_notif_read', 'ui_notif_replace', 'ui_notif_open', 'ui_question_close', 'ui_answer_receipt',
+ 'utf8_trim', 'swarm_notice', 'swarm_notice_mark', 'swarm_notice_raise', 'swarm_notice_drop', 'swarm_events',
+ 'swarm_tabs_changed', 'ui_supertabs_ids', 'ui_supertab', 'ui_supertab_recap', 'ui_supertab_focus',
+ 'ui_supertab_wait', 'ui_supertab_wait_close', 'ui_supertabs_clear']:
code += function(name)
code += '#define ui_notify_task_done(a,b,c,d) ui_notify_summary(a,b,c,d,"alert",false,false)\n'
for name in ['event', 'ui_project_emit', 'ui_project_restore_event', 'ui_project_clear_event', 'ui_project_set_name', 'ui_project_remove', 'ui_project_clear_all', 'ui_project_apply_order']:
@@ -235,6 +252,12 @@ code+='static void visit_work(action_t a) { switch(a.kind) { case A_VISIT_SEND:'
carry_actions = source.split('case A_CARRY:\n',1)[1].split('case A_NAP:',1)[0]
code += 'static void carry_action(action_t a) { switch(a.kind) { case A_CARRY:\n' + carry_actions + 'default: break; } }\n'
code += 'static void dispatch(action_t a);\n'
+lead_actions = source.split(' case A_LEAD: {',1)[1].split(' case A_READER:',1)[0]
+panes_actions = source.split(' case A_AGENTS: {',1)[1].split(' case A_AGENT: {',1)[0]
+code += '#define TAB_ROWS 4\nstatic void panes_action(action_t a) { switch(a.kind) { case A_AGENTS: {'+panes_actions+'default: break; } }\n'
+stop_actions = source.split(' case A_STOP_YES:\n',1)[1].split(' case A_MODELS:',1)[0]
+code += 'static void stop_action(action_t a) { switch(a.kind) { case A_STOP_YES:\n'+stop_actions+'default: break; } }\n'
+code += 'static void lead_action(action_t a) { switch(a.kind) { case A_LEAD: {'+lead_actions+'default: break; } }\n'
question_actions = source.split(' case A_QUESTION_CHOICES:\n',1)[1].split(' case A_INBOX:',1)[0]
code += 'static void question_action(action_t a) { switch(a.kind) { case A_QUESTION_CHOICES:\n'+question_actions+'default: break; } }\n'
draft_actions = source.split(' case A_DRAFT_EDIT:\n',1)[1].split(' case A_HOME:',1)[0]
@@ -257,6 +280,8 @@ static void dispatch(action_t a) {
starts++; COPY(target, a.id); COPY(s.voice_target, a.value==7 ? "Find in output" : active()->name);
s.voice_engine[0]=0; // as the real dispatch: the recipient's engine, none for Find / form / draft voice
for (int i=0;i<s.count;i++) if (a.value!=2 && a.value!=5 && a.value!=6 && a.value!=7 && !strcmp(s.agents[i].id,a.id)) COPY(s.voice_engine,s.agents[i].engine);
+ const ht_lead_t *lead = voice_lead(a.id, a.value); // and a Swarm's Lead's, by its harness
+ if (lead) { COPY(s.voice_engine, lead->engine); COPY(s.voice_target, lead->project); }
s.voice_carry=a.value==3; s.voice_search=a.value==7; COPY(voice_context,a.text);
s.voice_return=s.view; s.voice_open = recording = true; view(VOICE);
} else if (a.kind == A_VOICE_STOP) { stops++; if(a.value==1)reviews++; recording = false; }
@@ -264,15 +289,15 @@ static void dispatch(action_t a) {
else if (a.kind == A_RETURN || a.kind == A_LATEST) { if(a.kind==A_RETURN)returns++; visit_action(a); }
else if (a.kind == A_PET) boops++;
else if (a.kind == A_TAB_LIST) tabs_open(); // mirrors ui_habitat.c's dispatch
+ else if (a.kind == A_LEAD) lead_action(a);
+ else if (a.kind == A_STOP_YES) stop_action(a);
else if (a.kind == A_AGENT) {
- switches++; s.active = 0; // the pane with that id, as ui_habitat.c's find
+ swarm_leave(); switches++; s.active = 0; // the pane with that id, as ui_habitat.c's find
for (int i = 0; i < s.count; i++) if (!strcmp(s.agents[i].id, a.id)) s.active = i;
view(AGENT);
} else if (a.kind == A_SETTINGS) view(SETTINGS);
else if (a.kind == A_FIND) view(FORM);
- else if (a.kind == A_AGENTS) { // mirrors ui_habitat.c: the pages open on the pane on the face
- view(AGENTS); ht_tab_carousel_reset(&pane_carousel, s.count, s.active >= 0 && s.active < s.count ? s.active : 0);
- }
+ else if (a.kind == A_AGENTS) panes_action(a); // ui_habitat.c's own: the pages open on the pane on the face
else if (a.kind == A_INBOX) notice_open();
else if (a.kind == A_HOME) view(HOME);
else if (a.kind == A_NOTICE) notice_action(a);
@@ -286,6 +311,7 @@ static void dispatch(action_t a) {
}
'''
code += function('habitat_touch') + function('habitat_touch_cancel') + function('habitat_next_wake_ms')
+code += 'static bool audio_client_active(void);\n' + function('ui_boot_pressed')
code += r'''
static ht_scene_t scene;
static void scene_take(void) {
@@ -320,6 +346,8 @@ static void reset(void) {
recording = congestion = false; starts = stops = boops = switches = question_sends = 0;
down_reports = moves = ups = travel = waiting_count = 0; target[0] = 0;
desktop_opens=0; opened_agent[0]=0; notice_reads_sent=0;
+ ht_supertabs_reset(&swarm); memset(&sw,0,sizeof sw); swarm_sent=0; stopped_agent[0]=0;
+ desk_row_count=0; desk_selected[0]=0;
scene_take();
}
static void workspace_setup(void) {
@@ -1307,10 +1335,421 @@ static void tab_frame_checks(void) {
puts("tab frames: long/UTF-8 names, bounds, clipped movement and exact partial redraw PASS");
reset();
}
+
+/*
+ * THE SWARMS (docs/superpowers/specs/2026-10-23-round-swarm-tab-design.md). Three Swarms: "openharness", open on the
+ * desktop as desk tab t1 (which counts no agents), and "studio" and "playground", which the desktop has not opened.
+ * openharness's Leads arrive in the daemon's urgency order and carry their project order.
+ */
+static ht_supertab_t card;
+static void card_begin(const char *id, const char *tab, const char *name) { assert(ht_supertab_init(&card, id, tab, name, 0)); }
+static void card_lead(const char *id, const char *project, const char *engine, const char *local, const char *state, int order, long since) {
+ ht_lead_in_t in = {.id = id, .project = project, .engine = engine, .local = local, .state = state, .order = order, .since = since};
+ assert(ht_supertab_lead_add(&card, &in));
+}
+static bool card_send(void) { card.count = card.lead_n; return ui_supertab(&card); }
+static void openharness_card(void) {
+ card_begin("s1", "t1", "openharness");
+ card_lead("L2", "docs", "claude", "h2", "ask", 2, -1);
+ card_lead("L3", "firmware", "codex", "h3", "stuck", 3, -1);
+ card_lead("L0", "mobile", "claude", "h0", "work", 0, 134);
+ card_lead("L4", "backend", "cursor", "", "work", 4, -1);
+ card_lead("L1", "Round dial firmware release candidate", "claude", "h1", "done", 1, -1);
+}
+static void swarm_setup(void) {
+ reset(); ht_character_select(&character, HT_CHARACTER_FOCUS); fake_ms = 100000;
+ static cable_swarm_t rows[3];
+ memset(rows, 0, sizeof rows);
+ COPY(rows[0].id, "t0"); COPY(rows[0].name, "Harness repo"); rows[0].agents = 1;
+ COPY(rows[1].id, "t1"); COPY(rows[1].name, "openharness"); rows[1].agents = 0;
+ COPY(rows[2].id, "t2"); COPY(rows[2].name, "Research"); rows[2].agents = 1;
+ ui_swarms_replace(rows, 3, "t0");
+ const char ids[3][ID_MAX] = {"s1", "s3", "s2"};
+ ui_supertabs_ids(ids, 3);
+ openharness_card(); card_send();
+ card_begin("s2", "", "playground"); card_lead("P0", "sandbox", "claude", "h9", "work", 0, 12); card_send();
+ card_begin("s3", "", "studio"); card_lead("K0", "sketches", "claude", "", "done", 0, -1);
+ card_lead("K1", "renders", "codex", "h7", "work", 1, 40); card_send();
+ swarm_sent = 0; scene_take();
+}
+static const ht_run_t *big_run(void) {
+ for (int i = 0; i < scene.count; i++) if (scene.runs[i].font == &ht_lv_inter_44.base && scene.runs[i].text[0]) return &scene.runs[i];
+ return NULL;
+}
+static void tabs_at(int index) { dispatch((action_t){.kind = A_TABS}); ht_tab_carousel_reset(&tab_carousel, tabs_total(), index); scene_take(); }
+static void swarm_tabs_checks(const char *dir) {
+ // A desk tab linked to a Swarm keeps its place and name, listed with no agents; it was hidden before the link came.
+ swarm_setup();
+ assert(s.tab_count == 3 && !strcmp(s.tabs[1].id, "t1") && !strcmp(s.tabs[1].name, "openharness"));
+ {
+ reset(); static cable_swarm_t rows[2]; memset(rows, 0, sizeof rows);
+ COPY(rows[0].id, "t0"); rows[0].agents = 1; COPY(rows[1].id, "t1"); rows[1].agents = 0;
+ ui_swarms_replace(rows, 2, "t0"); assert(s.tab_count == 1);
+ const char ids[1][ID_MAX] = {"s1"}; ui_supertabs_ids(ids, 1); openharness_card(); card_send();
+ assert(s.tab_count == 2 && !strcmp(s.tabs[1].id, "t1"));
+ }
+ // The unopened Swarms follow the desk tabs in the `supertabs` order, not the order their cards came in.
+ swarm_setup();
+ assert(tabs_total() == 5 && !strcmp(tab_label(3), "studio") && !strcmp(tab_label(4), "playground"));
+ assert(!strcmp(tab_id_at(1), "t1") && !strcmp(tab_id_at(3), "s3") && !strcmp(tab_id_at(4), "s2"));
+ // Decision 1: a Swarm's page is drawn as any tab's. The centred name of the unopened "playground" and of the desk
+ // tab "Research" share font and ink.
+ tabs_at(2); const ht_run_t desk = *big_run();
+ tabs_at(4); const ht_run_t far = *big_run();
+ assert(!strcmp(far.text, "playground") && far.font == desk.font && far.fg == desk.fg && far.bg == desk.bg);
+ // 1a in "Harness repo", openharness at the right edge; 1b dragging; 1c on openharness; 1d the unopened playground.
+ swarm_setup(); tabs_at(0); FOCUS_PAGE("swarm-tabs-1a");
+ tab_carousel.position = HT_TAB_PITCH / 2; FOCUS_PAGE("swarm-tabs-1b");
+ tabs_at(1); assert(!strcmp(big_run()->text, "openharness")); FOCUS_PAGE("swarm-tabs-1c");
+ tabs_at(4); FOCUS_PAGE("swarm-tabs-1d");
+ // A tap on an unopened Swarm's name enters it: no workspace handshake, no switching view, then select and open
+ // for its first Lead by order.
+ int switched = tab_switches;
+ tap(5000, 233, 233);
+ assert(s.view == HOME && swarm_mode() && !strcmp(sw.tab, "s2") && !strcmp(sw.lead, "P0"));
+ assert(tab_switches == switched && workspace.phase == HT_WORKSPACE_IDLE && !s.loading);
+ assert(swarm_sent == 3 && !strcmp(swarm_wire[0], "select s2 P0") && !strcmp(swarm_wire[1], "open s2 P0") &&
+ !strcmp(swarm_wire[2], "recap.get s2 P0"));
+ // Done on a Swarm the desktop last showed at a Lead opens on that Lead; the Swarm the dial left is closed.
+ ui_supertab_focus("s3", "K1"); assert(!strcmp(sw.tab, "s2"));
+ tabs_at(3); swarm_sent = 0; dispatch((action_t){.kind = A_TAB_DONE});
+ assert(!strcmp(sw.tab, "s3") && !strcmp(sw.lead, "K1") && s.view == HOME && tab_switches == switched);
+ assert(!strcmp(swarm_wire[0], "open s2 ") && !strcmp(swarm_wire[1], "select s3 K1") && !strcmp(swarm_wire[2], "open s3 K1"));
+ // The desk tab linked to openharness enters the Swarm too, at its first project by order ("mobile").
+ tabs_at(1); dispatch((action_t){.kind = A_TAB_DONE});
+ assert(!strcmp(sw.tab, "s1") && !strcmp(sw.lead, "L0") && tab_switches == switched);
+ // Hold on a Swarm's face opens TABS on that Swarm.
+ s.view = HOME; scene_take();
+ habitat_touch(true, 233, 230, 9000); habitat_touch(true, 233, 230, 9700);
+ assert(s.view == TABS && ht_tab_carousel_index(&tab_carousel) == 1 && !starts);
+ habitat_touch(false, 233, 230, 9800);
+ // An ordinary desk tab still takes the workspace handshake, and leaving the Swarm says so.
+ swarm_sent = 0; ht_tab_carousel_reset(&tab_carousel, tabs_total(), 2); scene_take();
+ dispatch((action_t){.kind = A_TAB_DONE});
+ assert(!swarm_mode() && !strcmp(tab_target, "t2") && tab_switches > switched && !strcmp(swarm_wire[0], "open s1 "));
+ puts("Swarm tabs: linked desk tab kept with no agents, unopened Swarms after the desk tabs in list order, same font and ink, entered with no handshake, remembered Lead, hold to TABS, desk tabs unchanged PASS");
+}
+
+// Every run's text joined, and the first sprite (the pet's frame): what a face says and which pose it holds.
+static bool scene_says(const char *needle) {
+ for (int i = 0; i < scene.count; i++) if (strstr(scene.runs[i].text, needle)) return true;
+ return false;
+}
+static const void *pet_frame(void) {
+ for (int i = 0; i < scene.count; i++) if (scene.runs[i].sprite.width) return scene.runs[i].sprite.cells;
+ return NULL;
+}
+// The frames the pet cycles through over six seconds: a pose is its loop, not one instant of it.
+static int pet_frames(const void *out[64]) {
+ int n = 0; uint32_t base = fake_ms;
+ for (uint32_t t = 0; t < 6000; t += 20) {
+ fake_ms = base + t; scene_take(); const void *f = pet_frame(); bool seen = false;
+ for (int i = 0; i < n; i++) seen |= out[i] == f;
+ if (!seen && n < 64) out[n++] = f;
+ }
+ fake_ms = base; scene_take();
+ return n;
+}
+static int card_lines(const char **last) {
+ int n = 0;
+ for (int i = 0; i < scene.count; i++) if (scene.runs[i].font == &ht_lv_inter_30.base && scene.runs[i].text[0]) { n++; *last = scene.runs[i].text; }
+ return n;
+}
+static bool wire_has(int from, const char *line) {
+ for (int i = from; i < swarm_sent; i++) if (!strcmp(swarm_wire[i], line)) return true;
+ return false;
+}
+static void enter_at(const char *tab, const char *lead) {
+ swarm_enter(ht_supertabs_find(&swarm, tab), lead, true); scene_take();
+}
+static void no_red(void) {
+ for (int i = 0; i < scene.count; i++) assert(scene.runs[i].fg != ERROR && scene.runs[i].box.fill != ERROR);
+}
+static void swarm_pane_checks(const char *dir) {
+ // openharness's Leads come in urgency order and are kept in project order.
+ swarm_setup(); const ht_supertab_t *t = ht_supertabs_find(&swarm, "s1");
+ assert(t->lead_n == 5 && !strcmp(t->leads[0].id, "L0") && !strcmp(t->leads[1].id, "L1") && !strcmp(t->leads[2].id, "L2") &&
+ !strcmp(t->leads[3].id, "L3") && !strcmp(t->leads[4].id, "L4"));
+ // 2a "mobile" working on this computer: the time since `since` on the lower arc, the project on the upper.
+ enter_at("s1", "L0"); assert(title_is("mobile") && scene_says("2:14"));
+ FOCUS_PAGE("swarm-2a");
+ fake_ms += 6000; scene_take(); assert(scene_says("2:20")); // the dial's own clock carries it on
+ // 2b a long name, done: the recap card. A recap for another Lead is dropped.
+ enter_at("s1", "L1");
+ ui_supertab_recap("s1", "L2", "Not this one.", 1792560000u, false); scene_take(); assert(!scene_says("Not this one."));
+ ui_supertab_recap("s1", "L1", "Release candidate built and checked on both dials.", 1792560000u, false); scene_take();
+ assert(scene_says("Release candidate built"));
+ FOCUS_PAGE("swarm-2b");
+ // 2g a 1,500-byte recap: four lines, the last ending in "…".
+ {
+ char longer[HT_SUPERTAB_TEXT]; size_t n = 0;
+ while (n + 6 < sizeof longer - 1) { memcpy(longer + n, "words ", 6); n += 6; }
+ longer[n] = 0;
+ ui_supertab_recap("s1", "L1", longer, 1792560000u, false); scene_take();
+ const char *last = ""; int lines = card_lines(&last);
+ assert(lines >= 1 && lines <= 4 && strstr(last, "\xe2\x80\xa6"));
+ FOCUS_PAGE("swarm-2g");
+ }
+ // 2f no message yet: the resting face, no card.
+ ui_supertab_recap("s1", "L1", "", 0, true); scene_take();
+ { const char *last; assert(!card_lines(&last)); }
+ // With nothing unread the bell leaves the lower arc to the resting face's one line, as in the mockup.
+ for (int i = 0; i < s.notice_count; i++) notice_mark_read(&s.notice[i]);
+ scene_take(); { bool line = false; for (int i = 0; i < scene.count; i++) line |= scene.runs[i].arc == 2 && scene.runs[i].text[0]; assert(line); }
+ FOCUS_PAGE("swarm-2f");
+ // 2c "docs" needs you, here: its wait's question takes the recap's place, in the asking pose.
+ enter_at("s1", "L2");
+ ui_supertab_recap("s1", "L2", "Docs drafted.", 1792560000u, false);
+ assert(!ui_supertab_wait("h2", "supertab:w1", "openharness", false, "Publish the docs today?")); // on the face: no beep
+ scene_take(); assert(scene_says("Publish the docs") && !scene_says("Docs drafted."));
+ FOCUS_PAGE("swarm-2c");
+ // 2d "firmware" stuck: the daemon's "Stuck: …" in the same card, and no red anywhere.
+ enter_at("s1", "L3");
+ ui_supertab_wait("h3", "supertab:w2", "openharness", true, "Stuck: the release key is missing."); scene_take();
+ assert(scene_says("Stuck: the release key")); no_red();
+ FOCUS_PAGE("swarm-2d");
+ // The asking pose: Codex's asking loop, not the finished one it shows once the same Lead is done with a message.
+ {
+ static const void *asking[64], *done[64]; int asking_n = pet_frames(asking);
+ card_begin("s1", "t1", "openharness"); openharness_card(); card.leads[1].state = HT_LEAD_DONE; // L3, firmware
+ assert(!strcmp(card.leads[1].id, "L3")); card_send(); ui_supertab_wait_close("h3", "supertab:w2");
+ ui_supertab_recap("s1", "L3", "Release key found; build signed.", 1792560000u, false);
+ int done_n = pet_frames(done); bool other = false;
+ for (int i = 0; i < asking_n; i++) { bool shared = false; for (int k = 0; k < done_n; k++) shared |= asking[i] == done[k]; other |= !shared; }
+ assert(asking_n && done_n && other);
+ openharness_card(); card_send();
+ }
+ // 2e "backend" on someone else's machine, working: "Working…" and no time; a tap on the face talks to nobody.
+ enter_at("s1", "L4"); assert(title_is("backend") && scene_says("Working") && !scene_says(":"));
+ FOCUS_PAGE("swarm-2e");
+ // (the real dispatch drops a face voice turn with no recipient: test_voice_ui.py)
+ assert(!make_action((hit_t){.action = A_VOICE}).id[0]);
+ enter_at("s1", "L0"); assert(!strcmp(make_action((hit_t){.action = A_VOICE}).id, "h0"));
+ tap(fake_ms, 233, 260); assert(!strcmp(target, "h0")); dispatch((action_t){.kind = A_VOICE_ABORT});
+ enter_at("s1", "L4");
+ // 2e' the same Lead asking: the asking pose and its last message, read-only.
+ card_begin("s1", "t1", "openharness");
+ card_lead("L0", "mobile", "claude", "h0", "work", 0, 134); card_lead("L1", "Round dial firmware release candidate", "claude", "h1", "done", 1, -1);
+ card_lead("L2", "docs", "claude", "h2", "ask", 2, -1); card_lead("L3", "firmware", "codex", "h3", "stuck", 3, -1);
+ card_lead("L4", "backend", "cursor", "", "ask", 4, -1); card_send();
+ ui_supertab_recap("s1", "L4", "Need a decision on the cache size.", 1792560000u, false); scene_take();
+ assert(scene_says("Need a decision") && !scene_says("Working"));
+ FOCUS_PAGE("swarm-2e-ask");
+ // 2h a Swarm with no projects: PANES' own empty page, and "Choose a tab" goes to TABS.
+ {
+ const char ids[4][ID_MAX] = {"s1", "s3", "s2", "s4"}; ui_supertabs_ids(ids, 4);
+ card_begin("s4", "", "empty"); card_send();
+ enter_at("s4", NULL); assert(scene_says("No panes in") && scene_says("this tab.") && scene_says("Choose a tab"));
+ FOCUS_PAGE("swarm-2h");
+ tap(fake_ms, 233, 365); assert(s.view == TABS);
+ }
+ // A swipe moves by order, wrapping, and says select, open and recap.get — never `focus` (no pane switch).
+ swarm_setup(); enter_at("s1", "L4"); swarm_sent = 0; int panes = switches;
+ habitat_touch(true, 320, 220, fake_ms); habitat_touch(false, 150, 220, fake_ms + 120); scene_take();
+ assert(!strcmp(sw.lead, "L0") && switches == panes);
+ assert(swarm_sent == 3 && !strcmp(swarm_wire[0], "select s1 L0") && !strcmp(swarm_wire[1], "open s1 L0") &&
+ !strcmp(swarm_wire[2], "recap.get s1 L0"));
+ habitat_touch(true, 150, 220, fake_ms + 1000); habitat_touch(false, 320, 220, fake_ms + 1120); scene_take();
+ assert(!strcmp(sw.lead, "L4") && switches == panes);
+ // No recap within 5 s: one more recap.get, and only one.
+ swarm_sent = 0; surface_tick(fake_ms + 4999); assert(!swarm_sent);
+ surface_tick(fake_ms + 5000); assert(swarm_sent == 1 && !strcmp(swarm_wire[0], "recap.get s1 L4"));
+ surface_tick(fake_ms + 11000); assert(swarm_sent == 1);
+ // PANES (tap the name): one page per Lead in order, opened on the one on the face; a long name on two lines with
+ // "…"; Done picks with the swipe's messages.
+ swarm_setup(); enter_at("s1", "L2"); tap(fake_ms, 233, 30);
+ assert(s.view == AGENTS && pane_carousel.count == 5 && ht_tab_carousel_index(&pane_carousel) == 2 && !strcmp(big_run()->text, "docs"));
+ FOCUS_PAGE("swarm-3a");
+ for (int i = 0; i < 5; i++) assert(!strcmp(pane_label(i), ht_supertabs_find(&swarm, "s1")->leads[i].project));
+ ht_tab_carousel_reset(&pane_carousel, 5, 1); scene_take();
+ {
+ int big = 0; bool cut = false;
+ for (int i = 0; i < scene.count; i++) if (scene.runs[i].font == &ht_lv_inter_44.base && scene.runs[i].text[0]) {
+ big++; size_t n = strlen(scene.runs[i].text); cut |= n > 3 && !strcmp(scene.runs[i].text + n - 3, "\xe2\x80\xa6");
+ }
+ assert(big == 2 && cut);
+ }
+ FOCUS_PAGE("swarm-3b");
+ swarm_sent = 0; tap(fake_ms + 2000, 233, 420);
+ assert(s.view == HOME && !strcmp(sw.lead, "L1") && wire_has(0, "select s1 L1") && wire_has(0, "open s1 L1") && wire_has(0, "recap.get s1 L1"));
+ // Twelve projects, twelve pages, the last one picked.
+ {
+ card_begin("s1", "t1", "openharness");
+ static const char *names[12] = {"mobile", "web", "docs", "firmware", "backend", "api", "infra", "design", "ops", "data", "growth", "support"};
+ char id[8];
+ for (int i = 0; i < 12; i++) { snprintf(id, sizeof id, "M%d", i); card_lead(id, names[i], i % 2 ? "codex" : "claude", "", "work", i, -1); }
+ card_send(); enter_at("s1", "M0"); tap(fake_ms, 233, 30);
+ assert(s.view == AGENTS && pane_carousel.count == 12);
+ ht_tab_carousel_reset(&pane_carousel, 12, 5); FOCUS_PAGE("swarm-3c");
+ ht_tab_carousel_reset(&pane_carousel, 12, 11); scene_take();
+ dispatch((action_t){.kind = A_LEAD, .id = "M11"}); assert(s.view == HOME && !strcmp(sw.lead, "M11") && sw.at == 11);
+ }
+ // Following the desktop: supertab.focus moves the face (no select back), but not while talking.
+ swarm_setup(); enter_at("s1", "L0"); swarm_sent = 0;
+ ui_supertab_focus("s1", "L3"); assert(!strcmp(sw.lead, "L3") && !wire_has(0, "select s1 L3") && wire_has(0, "open s1 L3"));
+ s.voice_open = true; ui_supertab_focus("s1", "L1"); assert(!strcmp(sw.lead, "L3")); s.voice_open = false;
+ // The desktop opening the Swarm's desk tab takes the dial in with it.
+ swarm_leave(); COPY(s.selected_tab, "t1"); s.view = HOME; ui_supertab_focus("s1", "L2");
+ assert(swarm_mode() && !strcmp(sw.tab, "s1") && !strcmp(sw.lead, "L2"));
+ // A new card without the Lead on the face: the face takes the Lead now at its place.
+ ui_supertab_focus("s1", "L3"); assert(sw.at == 3);
+ card_begin("s1", "t1", "openharness");
+ card_lead("L0", "mobile", "claude", "h0", "work", 0, 134); card_lead("L1", "Round dial firmware release candidate", "claude", "h1", "done", 1, -1);
+ card_lead("L2", "docs", "claude", "h2", "ask", 2, -1); card_lead("L4", "backend", "cursor", "", "work", 4, -1); card_send();
+ assert(!strcmp(sw.lead, "L4") && sw.at == 3);
+ // The Swarm gone from the list: back to TABS.
+ { const char ids[2][ID_MAX] = {"s3", "s2"}; ui_supertabs_ids(ids, 2); }
+ assert(!swarm_mode() && s.view == TABS);
+ // The side button: STOP for a busy Lead on this computer (its harness id), HOME for a remote one.
+ swarm_setup(); enter_at("s1", "L0"); ui_boot_pressed(); assert(s.view == STOP && !strcmp(s.stop_agent, "h0"));
+ dispatch((action_t){.kind = A_STOP_YES}); assert(!strcmp(stopped_agent, "h0") && s.view == HOME);
+ s.stop_agent[0] = 0; enter_at("s1", "L4"); ui_boot_pressed(); assert(s.view == HOME && !s.stop_agent[0]);
+ puts("Swarm panes: project order, faces 2a-2h (time, recap card and cut, resting, wait text, stuck without red, remote read-only), swipe with wrap and no focus, one recap retry, PANES 3a-3c, follow the desktop, Lead gone, Swarm gone, side button PASS");
+}
+
+// The dial's own entry for a Lead, its index in the inbox, or -1.
+static int swarm_entry(const char *lead) {
+ for (int i = 0; i < s.notice_count; i++) if (s.notice[i].swarm && !strcmp(s.notice[i].agent_id, lead)) return i;
+ return -1;
+}
+static void inbox_at(const char *lead) {
+ ui_notif_open(); s.offset = swarm_entry(lead); assert(s.offset >= 0); scene_take();
+}
+// One run's ink and face, by its text.
+static const ht_run_t *run_of(const char *text) {
+ for (int i = 0; i < scene.count; i++) if (!strcmp(scene.runs[i].text, text)) return &scene.runs[i];
+ return NULL;
+}
+// openharness with every Lead working, so a test raises exactly the Leads it means to.
+static void calm_card(const char *backend, const char *docs) {
+ card_begin("s1", "t1", "openharness");
+ card_lead("L0", "mobile", "claude", "h0", "work", 0, 134); card_lead("L1", "Round dial firmware release candidate", "claude", "h1", "done", 1, -1);
+ card_lead("L2", "docs", "claude", "h2", docs, 2, -1); card_lead("L3", "firmware", "codex", "h3", "work", 3, -1);
+ card_lead("L4", "backend", "cursor", "", backend, 4, -1);
+}
+static void swarm_inbox_checks(const char *dir) {
+ // The fixture's card raised docs (ask) and firmware (stuck), each once, with the approved fixed lines.
+ swarm_setup();
+ assert(swarm_entry("L2") >= 0 && swarm_entry("L3") >= 0 && swarm_entry("L0") < 0 && swarm_entry("L4") < 0);
+ assert(!strcmp(s.notice[swarm_entry("L2")].summary, "Needs you. Answer on the desktop."));
+ assert(!strcmp(s.notice[swarm_entry("L3")].summary, "Stuck. See the desktop."));
+ assert(s.notice[swarm_entry("L2")].question && s.notice[swarm_entry("L2")].swarm == 1 && s.notice[swarm_entry("L3")].swarm == 2);
+ // 4e a Lead on someone else's machine, done/work -> ask: one entry and one beep; the Swarm's name grey, the
+ // project green. Asking again raises nothing; stuck changes the line and beeps; back to work removes it.
+ calm_card("work", "ask"); assert(!card_send());
+ calm_card("ask", "ask"); assert(card_send());
+ int e = swarm_entry("L4"); assert(e >= 0 && !strcmp(s.notice[e].summary, "Needs you. Answer on the desktop."));
+ calm_card("ask", "ask"); assert(!card_send());
+ inbox_at("L4");
+ {
+ const ht_run_t *grey = run_of("openharness"), *green = run_of("backend");
+ assert(grey && grey->font == &ht_lv_inter_25.base && grey->fg == color(0x8a8a99));
+ assert(green && green->font == &ht_lv_inter_25.base && green->fg == color(0x04fe08));
+ assert(scene_says("Needs you."));
+ }
+ FOCUS_PAGE("swarm-4e");
+ calm_card("stuck", "ask"); assert(card_send());
+ assert(!strcmp(s.notice[swarm_entry("L4")].summary, "Stuck. See the desktop."));
+ calm_card("work", "ask"); assert(!card_send()); assert(swarm_entry("L4") < 0);
+ // 4c, 4d the local Leads' waits: their questions take the fixed lines' place, with no second beep.
+ swarm_setup();
+ assert(!ui_supertab_wait("h2", "supertab:w1", "openharness", false, "Publish the docs today?"));
+ assert(!ui_supertab_wait("h3", "supertab:w2", "openharness", true, "Stuck: the release key is missing."));
+ assert(!strcmp(s.notice[swarm_entry("L2")].summary, "Publish the docs today?"));
+ assert(!strcmp(s.notice[swarm_entry("L3")].summary, "Stuck: the release key is missing."));
+ // A Super Tab wait never opens the question screen, whatever the dial shows.
+ assert(s.view == HOME);
+ { cable_notif_t desk = {.agent_id = "a", .name = "Payments refactor", .machine = "MacBook", .summary = "Hero and pricing are in."};
+ ui_notif_replace(&desk, 1); }
+ inbox_at("L2"); assert(scene_says("Publish the docs") && run_of("openharness") && run_of("docs"));
+ FOCUS_PAGE("swarm-4c");
+ inbox_at("L3"); assert(scene_says("Stuck: the release key"));
+ FOCUS_PAGE("swarm-4d");
+ // question.close: the fixed line again while the Lead still asks, and no beep.
+ ui_supertab_wait_close("h2", "supertab:other"); assert(!strcmp(s.notice[swarm_entry("L2")].summary, "Publish the docs today?"));
+ ui_supertab_wait_close("h2", "supertab:w1"); assert(!strcmp(s.notice[swarm_entry("L2")].summary, "Needs you. Answer on the desktop."));
+ // The wait first, then the Lead's state: one entry, one beep. The state first, then the wait: the same.
+ {
+ reset(); ht_character_select(&character, HT_CHARACTER_FOCUS); fake_ms = 100000;
+ const char ids[1][ID_MAX] = {"s1"}; ui_supertabs_ids(ids, 1);
+ calm_card("work", "work"); assert(!card_send());
+ int before = s.notice_count;
+ assert(ui_supertab_wait("h2", "supertab:w1", "openharness", false, "Publish the docs today?")); // the wait beeps
+ calm_card("work", "ask"); assert(!card_send()); // the state does not
+ assert(s.notice_count == before + 1 && !strcmp(s.notice[swarm_entry("L2")].summary, "Publish the docs today?"));
+ calm_card("work", "ask"); assert(!card_send());
+ ui_supertab_wait_close("h2", "supertab:w1"); calm_card("work", "work"); assert(!card_send()); assert(swarm_entry("L2") < 0);
+ calm_card("work", "ask"); assert(card_send());
+ assert(!ui_supertab_wait("h2", "supertab:w3", "openharness", false, "Ship it?"));
+ int count = 0; for (int i = 0; i < s.notice_count; i++) count += !strcmp(s.notice[i].agent_id, "L2");
+ assert(count == 1 && !strcmp(s.notice[swarm_entry("L2")].summary, "Ship it?"));
+ }
+ // A wait from a harness that is no Lead's: nothing.
+ { int before = s.notice_count; assert(!ui_supertab_wait("h99", "supertab:w9", "openharness", false, "Worker question"));
+ assert(s.notice_count == before && !scene_says("Worker question")); }
+ // The desktop's snapshot replaces its own rows only: every Swarm entry stays, after it and before it.
+ swarm_setup();
+ { cable_notif_t desk[2] = {{.agent_id = "a", .name = "Payments refactor", .summary = "Shipped."}, {.agent_id = "b", .name = "Agent B", .summary = "Done."}};
+ ui_notif_replace(desk, 2); assert(swarm_entry("L2") >= 0 && swarm_entry("L3") >= 0 && s.notice_count == 4);
+ ui_notif_replace(desk, 0); assert(swarm_entry("L2") >= 0 && swarm_entry("L3") >= 0 && s.notice_count == 2); }
+ // An entry for the Lead on the face is read at once, with no beep.
+ swarm_setup(); enter_at("s1", "L4");
+ calm_card("ask", "ask"); assert(!card_send()); assert(swarm_entry("L4") >= 0 && s.notice[swarm_entry("L4")].read_on_dial);
+ // 4a in a desk tab, the bell pill at y 400 counts the Swarm entries; 4b on a working Clawd, its bubble instead.
+ swarm_setup(); scene_take();
+ { bool pill = false; for (int i = 0; i < scene.count; i++) pill |= scene.runs[i].box.h == 32 && scene.runs[i].y == 400;
+ assert(pill && action_enabled(A_INBOX) && run_of("2")); }
+ FOCUS_PAGE("swarm-4a");
+ enter_at("s1", "L0"); fake_ms += 2000; scene_take(); // the bubble has popped in
+ { bool pill = false; for (int i = 0; i < scene.count; i++) pill |= scene.runs[i].box.h == 32 && scene.runs[i].y == 400;
+ assert(!pill && action_enabled(A_INBOX)); }
+ FOCUS_PAGE("swarm-4b");
+ // Pull down from the face opens the inbox; a tap on a Swarm entry enters that Swarm at that Lead.
+ swarm_setup(); inbox_at("L3"); tap(fake_ms, 233, 233);
+ assert(swarm_mode() && !strcmp(sw.tab, "s1") && !strcmp(sw.lead, "L3") && s.view == HOME && !desktop_opens);
+ // Link lost: the Swarms and their entries go; the desktop's rows stay.
+ swarm_setup();
+ { cable_notif_t desk = {.agent_id = "a", .name = "Payments refactor", .summary = "Shipped."}; ui_notif_replace(&desk, 1); }
+ enter_at("s1", "L0"); ui_supertabs_clear();
+ assert(!swarm_mode() && swarm_entry("L2") < 0 && swarm_entry("L3") < 0 && s.notice_count == 1 && tabs_total() == 2);
+ // 4f nothing left: the existing empty inbox.
+ ui_notif_replace(NULL, 0); assert(!s.notice_count); view(INBOX); scene_take(); assert(scene_says("No notification"));
+ FOCUS_PAGE("swarm-4f");
+ puts("Swarm inbox: one entry per Lead, fixed lines, one beep (raise, stuck, either order with a wait), wait text and its close, never a question screen, no worker entries, kept across notif.replace, read on the face, bell pill and bubble, tap enters the Swarm, cleared on link loss PASS");
+}
+
+static int voice_bars(void) {
+ int n = 0;
+ for (int i = 0; i < scene.count; i++) n += scene.runs[i].font == &ht_wave && scene.runs[i].text[0];
+ return n;
+}
+static void swarm_voice_checks(const char *dir) {
+ // 5a-5d "mobile" on this computer: a tap on its face talks to its harness, with Clawd listening, then sending, then
+ // the Swarm's face again.
+ swarm_setup(); enter_at("s1", "L0"); FOCUS_PAGE("swarm-5a");
+ tap(fake_ms, 233, 260);
+ assert(s.view == VOICE && !strcmp(target, "h0") && !strcmp(s.voice_engine, "claude") && !strcmp(s.voice_target, "mobile"));
+ assert(!voice_bars()); FOCUS_PAGE("swarm-5b");
+ s.voice_waiting = true; FOCUS_PAGE("swarm-5c");
+ dispatch((action_t){.kind = A_VOICE_ABORT}); s.voice_waiting = false; scene_take();
+ assert(s.view == HOME && swarm_mode() && !strcmp(sw.lead, "L0") && title_is("mobile"));
+ FOCUS_PAGE("swarm-5d");
+ // 5e an engine with no listening scene: the seven bars.
+ card_begin("s2", "", "playground"); card_lead("P0", "agents", "opencode", "h9", "work", 0, 12); card_send();
+ fake_ms += 3000; enter_at("s2", "P0"); tap(fake_ms, 233, 260);
+ assert(s.view == VOICE && !strcmp(target, "h9") && !strcmp(s.voice_engine, "opencode") && voice_bars() == 7);
+ FOCUS_PAGE("swarm-5e");
+ dispatch((action_t){.kind = A_VOICE_ABORT});
+ puts("Swarm voice: a local Lead's face talks to its harness with its engine's scene or the seven bars, and returns to the Swarm's face PASS");
+}
int main(int argc, char **argv) {
test_character = getenv("HABITAT_TEST_TUX") ? HT_CHARACTER_TUX : HT_CHARACTER_TIM;
notification_read_checks(argc>1 ? argv[1] : NULL);
bell_checks(argc>1 ? argv[1] : NULL);
+ swarm_tabs_checks(argc>1 ? argv[1] : NULL);
+ swarm_pane_checks(argc>1 ? argv[1] : NULL);
+ swarm_inbox_checks(argc>1 ? argv[1] : NULL);
+ swarm_voice_checks(argc>1 ? argv[1] : NULL);
// The companion screen is gone: character, edge text and still-character are the app's now
// (Settings > Autonomous robots). What the glass kept is actions, and Nap is the one that moved
// off that screen into the controls list.
@@ -2873,7 +3312,7 @@ with tempfile.TemporaryDirectory(prefix='harness-touch-ui-') as d:
'-fsanitize='+os.environ.get('SANITIZERS','undefined,bounds'),
*extra_includes, '-I',str(native),str(out/'touch_ui.c'), *extra_sources, str(native/'gestures.c'),
str(native/'form.c'),str(native/'visit.c'),str(native/'draft.c'), str(native/'scroll.c'),str(native/'selection.c'),str(native/'carry.c'),str(native/'tim.c'),str(native/'character_motion.c'),str(native/'character_layout.c'),str(native/'character.c'),str(native/'illustrated.c'),str(native/'tux.c'),str(native/'focus.c'),str(native/'lvgl_fonts.c'),str(native/'lvgl_icons.c'),str(native/'focus_marks.c'),str(native/'focus_faces.c'),str(native/'pets.c'),str(native/'../../pet_store.c'),str(native/'../../elapsed.c'),str(native/'terminal.c'),
- str(native/'fonts.c'),str(native/'octopus.c'),str(native/'ascii_clip.c'),str(native/'octopus_font.c'),str(native/'workspace.c'),str(native/'command_face.c'),'-o',str(out/'touch_ui'),'-lm'],check=True)
+ str(native/'fonts.c'),str(native/'octopus.c'),str(native/'ascii_clip.c'),str(native/'octopus_font.c'),str(native/'workspace.c'),str(native/'supertab.c'),str(native/'command_face.c'),'-o',str(out/'touch_ui'),'-lm'],check=True)
args=[str(out/'touch_ui')]
if os.environ.get('HABITAT_PREVIEW_DIR'):
dest=Path(os.environ['HABITAT_PREVIEW_DIR']);dest.mkdir(parents=True,exist_ok=True)
diff --git a/devices/harness-device/firmware/test/test_voice_ui.py b/devices/harness-device/firmware/test/test_voice_ui.py
index 3c2dafe97..0afadac27 100644
--- a/devices/harness-device/firmware/test/test_voice_ui.py
+++ b/devices/harness-device/firmware/test/test_voice_ui.py
@@ -10,7 +10,7 @@ import subprocess
import tempfile
native = Path(__file__).resolve().parent / '../main/ui/habitat'
-source = (native / 'ui_habitat.c').read_text()
+source = Path(os.environ.get('UI_SOURCE', native / 'ui_habitat.c')).read_text()
def function(name):
@@ -35,6 +35,8 @@ static bool cable_client_supports(uint32_t features) { return (host_features & f
#include "form.h"
#include "draft.h"
#include "workspace.h"
+#include "supertab.h"
+#define EXT_RAM_BSS_ATTR
enum { HOME, AGENTS, AGENT, COMPANION, VOICE, MESSAGE, SELECTION, FORM, QUESTION, CHOICE, ANSWER_REVIEW, DRAFT, DRAFT_OPTIONS, INBOX };
enum { A_VOICE, A_VOICE_STOP, A_VOICE_ABORT };
enum { VOICE_CMD_NONE, VOICE_CMD_GOAL };
@@ -88,8 +90,9 @@ void audio_client_stop(void) { stops++; }
void audio_client_request_review(void) { reviews++; }
void audio_client_abort(void) { aborts++; abort_requested = true; }
void audio_client_copy_upload_id(char *dst, size_t cap) { snprintf(dst, cap, "capture-%d", starts); }
+static char started_for[64];
void audio_client_start_cable(const char *id, int cmd) {
- (void)id; (void)cmd; starts++; audio_active = recording = true; abort_requested = false;
+ (void)cmd; snprintf(started_for, sizeof started_for, "%s", id ? id : ""); starts++; audio_active = recording = true; abort_requested = false;
}
void audio_client_start_search(const char *id, const char *selected, unsigned revision) {
assert(!strcmp(selected,"search-test") && revision==3); audio_client_start_cable(id,VOICE_CMD_NONE);
@@ -116,6 +119,9 @@ bool is_question(const char *id) { (void)id; return false; }
void open_question(void) { assert(false); }
bool queue(action_t action) { if (queue_full) return false; queued = action; return true; }
'''
+# The Swarm's data and lookups, for the Lead a face voice turn goes to.
+harness += source[source.index('enum { SUPERTAB_RECAP_GET'):source.index('static const char *swarm_fixed_text(')]
+harness += function('voice_lead')
harness += function('question_view') + function('copy') + function('input_cancel') + function('view') + function('voice_close') + function('workspace_failed')
dispatch = source.split('case A_VOICE:\n', 1)[1].split('case A_PET:', 1)[0]
harness += 'static void dispatch(action_t a) { switch (a.kind) { case A_VOICE:\n' + dispatch + '} }\n'
@@ -142,6 +148,28 @@ static void begin(void) { speak(); work(queued); assert(recording && s.view == V
int main(void) {
// The listening scene follows whom the turn is for: an agent's engine, nothing for a draft.
reset(); strcpy(s.agents[0].engine, "claude"); begin(); assert(!strcmp(s.voice_engine, "claude"));
+ // In a Swarm the face's turn goes to the Lead's harness on this computer, never the Lead id, with the Lead's
+ // engine and project; it comes back to the Swarm's face.
+ {
+ static ht_supertab_t card; static ht_lead_event_t ev[4];
+ assert(ht_supertab_init(&card, "s1", "", "openharness", 2));
+ ht_lead_in_t mobile = {.id = "L1", .project = "mobile", .engine = "codex", .local = "h1", .state = "work", .order = 0, .since = 5};
+ ht_lead_in_t web = {.id = "L2", .project = "web", .engine = "claude", .local = "", .state = "work", .order = 1, .since = -1};
+ assert(ht_supertab_lead_add(&card, &mobile) && ht_supertab_lead_add(&card, &web));
+ const char ids[1][ID_MAX] = {"s1"};
+ reset(); ht_supertabs_reset(&swarm); memset(&sw, 0, sizeof sw);
+ ht_supertabs_ids(&swarm, ids, 1, ev, 4); ht_supertabs_put(&swarm, &card, now, ev, 4);
+ strcpy(sw.tab, "s1"); strcpy(sw.lead, "L1");
+ dispatch((action_t){.kind = A_VOICE, .id = "h1"}); work(queued);
+ assert(recording && s.view == VOICE && !strcmp(started_for, "h1"));
+ assert(!strcmp(s.voice_engine, "codex") && !strcmp(s.voice_target, "mobile"));
+ done(); finish_audio(); ui_voice_routed(true, false, "", "h1", "mobile", 1);
+ assert(s.view == AGENT && !s.voice_open && !strcmp(sw.tab, "s1") && !strcmp(sw.lead, "L1"));
+ // A desk pane's id while a Lead is on the face is no Lead's harness: the pane's own engine.
+ strcpy(s.agents[0].engine, "claude"); begin();
+ assert(!strcmp(started_for, "agent") && !strcmp(s.voice_engine, "claude"));
+ ht_supertabs_reset(&swarm); memset(&sw, 0, sizeof sw);
+ }
reset(); host_features=0; begin(); dispatch((action_t){.kind=A_VOICE_STOP,.value=1});
assert(!reviews && !s.voice_review && s.voice_waiting);
reset(); begin(); dispatch((action_t){.kind=A_VOICE_STOP,.value=1});
@@ -295,6 +323,6 @@ with tempfile.TemporaryDirectory(prefix='harness-voice-ui-') as directory:
(root / 'voice_ui.c').write_text(harness)
subprocess.run(['cc', '-std=c11', '-D_POSIX_C_SOURCE=200809L', '-Wall', '-Wextra', '-Werror', '-O1', '-g',
'-fsanitize=' + os.environ.get('SANITIZERS', 'undefined,bounds'),
- '-I', str(native), str(root / 'voice_ui.c'), str(native / 'selection.c'), str(native / 'carry.c'), str(native / 'visit.c'), str(native / 'form.c'), str(native / 'draft.c'), str(native / 'workspace.c'),
+ '-I', str(native), str(root / 'voice_ui.c'), str(native / 'selection.c'), str(native / 'carry.c'), str(native / 'visit.c'), str(native / 'form.c'), str(native / 'draft.c'), str(native / 'workspace.c'), str(native / 'supertab.c'),
'-o', str(root / 'voice_ui')], check=True)
subprocess.run([str(root / 'voice_ui')], check=True)
diff --git a/devices/harness-device/firmware/test/test_workspace.c b/devices/harness-device/firmware/test/test_workspace.c
index 98a6240fe..21095f22f 100644
--- a/devices/harness-device/firmware/test/test_workspace.c
+++ b/devices/harness-device/firmware/test/test_workspace.c
@@ -6,6 +6,11 @@
static void carousel(void)
{
ht_tab_carousel_t c={0};
+ // 24 desk tabs and 16 Swarms page as one list; more than that is cut.
+ ht_tab_carousel_reset(&c,40,39);
+ assert(c.count==40 && ht_tab_carousel_index(&c)==39);
+ ht_tab_carousel_reset(&c,41,40);
+ assert(c.count==40 && ht_tab_carousel_index(&c)==39);
ht_tab_carousel_reset(&c,0,0);
ht_tab_carousel_begin(&c,233,100);
assert(!c.touching && !ht_tab_carousel_end(&c,233,false,175));
@@ -63,7 +68,7 @@ static void carousel(void)
ht_tab_carousel_tick(&c,3000);
assert(ht_tab_carousel_index(&c)==10);
ht_tab_carousel_reset(&c,100,999);
- assert(c.count==24 && ht_tab_carousel_index(&c)==23);
+ assert(c.count==40 && ht_tab_carousel_index(&c)==39);
puts("tab carousel: short slow swipes, 2:1 tracking, bounded flicks, soft edges, settled taps, brake, cancel and clock wrap PASS");
}
diff --git a/docs/superpowers/plans/2026-10-23-round-swarm-tab.md b/docs/superpowers/plans/2026-10-23-round-swarm-tab.md
new file mode 100644
index 000000000..18ce8f63d
--- /dev/null
+++ b/docs/superpowers/plans/2026-10-23-round-swarm-tab.md
@@ -0,0 +1,305 @@
+# Round Dial Swarm Tab Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** On the round dial a Swarm is one more tab. Its projects are panes (their Leads) in the app's order. A Lead that needs you beeps and adds one inbox entry, even when it runs on another machine. You can talk to a Lead on this computer; a remote Lead is read-only.
+
+**Architecture:**
+- **Daemon.** The daemon already serves the Pro's Swarm frames (#1537) and Super Tab waits to any device whose hello names `swarmCard:"v1"` / `superTab:"wait-v1"`. It gains one field, `leads[i].order`.
+- **Firmware model.** The round firmware names both capabilities, parses the frames in `cable_client.c`, and keeps the Swarms in a new pure module (`supertab.c`).
+- **Firmware UI.** `ui_habitat.c` feeds the module's Swarms into the existing Focus screens: the TABS carousel, the agent face, PANES, the inbox and voice.
+
+**Tech Stack:** TypeScript (cli, vitest); C on ESP-IDF 5.5.4 for the ESP32-S3 round dial (`devices/harness-device/firmware`, host tests with `cc` and python fixtures).
+
+**Spec:** `docs/superpowers/specs/2026-10-23-round-swarm-tab-design.md`
+
+## Global Constraints
+
+- **Decisions are fixed** (spec "Decisions"):
+ - a Swarm tab is drawn like any tab;
+ - Swarms the desktop has not opened come after the desk tabs;
+ - projects keep `order`;
+ - remote Leads beep and add a read-only entry; there is no remote reply;
+ - Leads only;
+ - no Home and no Pro card.
+- **Wire:**
+ - only `order` is new;
+ - no new frame and no `CABLE_PROTO_VERSION` bump;
+ - the Pro firmware ignores `order` and is not changed.
+- **Limits:**
+ - 16 Swarms, 12 Leads each;
+ - names ≤48 bytes;
+ - recap ≤1,500 bytes, one slot only (the Lead on the face);
+ - every frame under the 512-token guard (`cable_json_guard.h`);
+ - the model lives in PSRAM (`EXT_RAM_BSS_ATTR`).
+- **On-device copy** (English, already approved): "Needs you. Answer on the desktop.", "Stuck. See the desktop.", and the existing "No panes in this tab.", "Choose a tab", "Working...", "No notification". No string names a Lead or a Product Manager.
+- **Every Focus page stays Inter-only, with ink inside r 230** (the `test_touch_ui.py` scans).
+- **Isolation:** no file under `devices/harness-pro/firmware` except `.md` may mention `harness-device`.
+- **Repo rules:**
+ - work in a worktree off current `main`;
+ - commit, push and open a PR only when the owner says so;
+ - dev firmware builds use `-DPROJECT_VER=0.0.99`, or the daemon's OTA replaces them;
+ - match the surrounding style and comment density.
+
+## Review Focus
+
+- A Super Tab wait must never open the round dial's question/answer screen (it cannot load one) — Task 6 tests.
+- `notif.replace` from the desktop must not drop the dial's own Swarm entries — Task 6 tests.
+- One beep for a Lead whose wait and state change arrive in either order — Task 6 tests.
+- A Lead id must never reach `focus`, `agent.open` or `voice.begin`; only `local` reaches voice — Tasks 5, 7 tests.
+- Entering a Swarm must not start the desk-tab workspace handshake (it would fail "That workspace is gone") — Task 4 tests.
+- The model is reset on link loss and rebuilt on attach without stale entries — Tasks 3, 6 tests.
+
+---
+
+### Task 1: Daemon — `order` on every Lead
+
+**Files:**
+- Modify: `cli/src/superTabs/cards.ts` (`SwarmLead`, `leadsOf` and its leading comment), `cli/src/cable/cableSession.ts` (`pushSwarmCards` frame), `devices/harness-pro/docs/cable.md` (`supertab` frame: optional `order`)
+- Test: `cli/src/superTabs/cards.spec.ts`, `cli/src/cable/cableSession.spec.ts`, `devices/harness-pro/firmware/test/test_pro_cable.c`
+
+**Interfaces:**
+- Produces: `SwarmLead.order: number` (0-based index in `state.projects`; the old-tab `lead` project is 0). On the wire: `"order":N` on each `supertab.leads[i]`.
+
+- [ ] **Step 1: Write failing tests.**
+ - `cards.spec.ts`:
+ - three projects with states done/ask/work come out ordered ask, work, done and carry `order` 1, 2, 0;
+ - 13 projects keep the 12 most urgent, with their original `order` (gaps allowed);
+ - an old tab without `projects` gives `order: 0`.
+ - `cableSession.spec.ts`:
+ - a `supertab` frame carries `order` per Lead;
+ - a round hello (`board` not `pro`) naming `swarmCard:"v1"` and `superTab:"wait-v1"` gets `supertabs`/`supertab` with no `seq`, and a Super Tab `question` with `superTab`/`attention`;
+ - a 16 × 12 list with `order` keeps each `supertab` under 512 JSON tokens.
+ - `test_pro_cable.c`: a `supertab` whose Leads carry `order` parses to the same model as one without.
+- [ ] **Step 2: Run** `cd cli && npx vitest run src/superTabs/cards.spec.ts src/cable/cableSession.spec.ts`. Expected: FAIL (no `order`). The Pro case passes already, which is the point: run `cd devices/harness-pro/firmware && bash test/run.sh`.
+- [ ] **Step 3: Implement.** In `leadsOf`, record the project index when building `leads`. In `pushSwarmCards`, copy `order: l.order` onto each Lead. Fix the comment "in project order then by urgency" to say what the code does. Document `order` in `cable.md`.
+- [ ] **Step 4: Run** the two specs, `npx vitest run src/superTabs src/cable`, and `npm run typecheck`. Expected: PASS. (`test:core` is not needed: no file under `src/core` or `src/services` changes.)
+- [ ] **Step 5: Commit** (when authorized) `feat(super-tabs): send each Lead's project order`.
+
+### Task 2: Round firmware — the `supertab` model
+
+**Files:**
+- Create: `devices/harness-device/firmware/main/ui/habitat/supertab.h`, `devices/harness-device/firmware/main/ui/habitat/supertab.c`, `devices/harness-device/firmware/test/test_supertab.c`
+- Modify: `devices/harness-device/firmware/main/CMakeLists.txt` (source list, beside `ui/habitat/workspace.c`), `devices/harness-device/firmware/test/run.sh` (build and run `test_supertab`)
+
+**Interfaces:**
+- Produces:
+ ```c
+ enum { HT_SUPERTABS_MAX = 16, HT_SUPERTAB_LEADS_MAX = 12, HT_SUPERTAB_NAME = 49, HT_SUPERTAB_TEXT = 1501 };
+ typedef enum { HT_LEAD_DONE, HT_LEAD_WORK, HT_LEAD_ASK, HT_LEAD_STUCK } ht_lead_state_t;
+ typedef struct { char id[ID_MAX], project_id[ID_MAX], project[HT_SUPERTAB_NAME], engine[12], owner[HT_SUPERTAB_NAME], local[ID_MAX];
+ ht_lead_state_t state, was; int order; uint32_t since_s, since_at_ms; } ht_lead_t;
+ typedef struct { char id[ID_MAX], tab[ID_MAX], name[HT_SUPERTAB_NAME]; uint16_t count; uint8_t lead_n; ht_lead_t leads[HT_SUPERTAB_LEADS_MAX]; } ht_supertab_t;
+ typedef enum { HT_RECAP_NONE, HT_RECAP_LOADING, HT_RECAP_LOADED, HT_RECAP_EMPTY } ht_recap_state_t;
+ typedef struct { ht_supertab_t tabs[HT_SUPERTABS_MAX]; int n; char ids[HT_SUPERTABS_MAX][ID_MAX]; int id_n;
+ struct { char tab[ID_MAX], lead[ID_MAX], text[HT_SUPERTAB_TEXT]; uint32_t at, asked_ms; ht_recap_state_t state; } recap; } ht_supertabs_t;
+ typedef enum { HT_LEAD_RAISED_ASK, HT_LEAD_RAISED_STUCK, HT_LEAD_CLEARED } ht_lead_event_kind_t;
+ typedef struct { ht_lead_event_kind_t kind; char tab[ID_MAX], lead[ID_MAX]; } ht_lead_event_t;
+ void ht_supertabs_reset(ht_supertabs_t *);
+ void ht_supertabs_ids(ht_supertabs_t *, const char ids[][ID_MAX], int n); // drops records gone from the list
+ int ht_supertabs_put(ht_supertabs_t *, const ht_supertab_t *in, uint32_t now_ms, // sorts leads by order (stable; frame order without it),
+ ht_lead_event_t *ev, int ev_max); // returns the transition events
+ const ht_supertab_t *ht_supertabs_find(const ht_supertabs_t *, const char *id);
+ const ht_supertab_t *ht_supertabs_for_desk(const ht_supertabs_t *, const char *desk_tab_id);
+ const ht_lead_t *ht_supertabs_lead_by_local(const ht_supertabs_t *, const char *harness_id, const ht_supertab_t **tab);
+ void ht_supertabs_recap_open(ht_supertabs_t *, const char *tab, const char *lead, uint32_t now_ms); // LOADING, clears text
+ bool ht_supertabs_recap_put(ht_supertabs_t *, const char *tab, const char *lead, const char *text, uint32_t at, bool none); // false: not the open Lead
+ ```
+- [ ] **Step 1: Write failing tests** in `test_supertab.c`:
+ - Leads sorted by `order` with ties stable, and kept in frame order when `order` is absent (-1).
+ - 13 Leads in → 12 kept; a name over 48 bytes is cut on a UTF-8 boundary; an id of `ID_MAX` bytes or more is rejected.
+ - Unknown state → DONE; a `put` for an id not in the last `ids` is dropped; `ids` without a Swarm drops its record.
+ - Transitions:
+ - DONE→ASK raises ASK once; ASK→ASK raises nothing; ASK→STUCK raises STUCK; STUCK→WORK clears;
+ - a Lead first seen in ASK raises ASK;
+ - a Lead gone from the frame clears.
+ - `for_desk` matches `tab`; `lead_by_local` matches `local` and never an empty `local`.
+ - Recap: `put` for another Lead returns false and stores nothing; a 1,600-byte text is cut to 1,500 on a UTF-8 boundary; `none` sets EMPTY; `reset` clears everything.
+- [ ] **Step 2: Run** `cd devices/harness-device/firmware && bash test/run.sh`. Expected: FAIL (no module).
+- [ ] **Step 3: Implement** `supertab.c` with no LVGL and no cJSON (the caller passes parsed structs), in the style of `workspace.c`.
+- [ ] **Step 4: Run** `bash test/run.sh`. Expected: PASS.
+- [ ] **Step 5: Commit** `feat(dial): a model of the Swarms and their Leads`.
+
+### Task 3: Round firmware — hello, parsing and the three requests
+
+**Files:**
+- Modify: `devices/harness-device/firmware/main/cable_client.c` (`send_hello`; the `t` dispatch near `swarms`/`question`/`question.close`; new `handle_supertabs`, `handle_supertab`, `handle_supertab_recap`, `handle_supertab_focus`; link-down reset), `devices/harness-device/firmware/main/cable_client.h` (`cable_client_supertab_send`), `devices/harness-device/firmware/main/ui/ui_screens.h` (UI entry points below)
+- Test: `devices/harness-device/firmware/test/test_cable_identity.py` (production handlers with real cJSON; needs `IDF_PATH`)
+
+**Interfaces:**
+- Consumes: Task 2.
+- Produces:
+ ```c
+ void cable_client_supertab_send(const char *t, const char *tab, const char *lead); // "supertab.recap.get" | "supertab.open" | "supertab.select"; lead "" only for open
+ void ui_supertabs_ids(const char ids[][ID_MAX], int n);
+ void ui_supertab(const ht_supertab_t *in);
+ void ui_supertab_recap(const char *tab, const char *lead, const char *text, uint32_t at, bool none);
+ void ui_supertab_focus(const char *tab, const char *lead);
+ void ui_supertab_wait(const char *agent_id, const char *request, const char *swarm_name, bool stuck, const char *text);
+ void ui_supertab_wait_close(const char *agent_id, const char *request);
+ ```
+- [ ] **Step 1: Write failing tests:**
+ - `hello` carries `"swarmCard":"v1"` and `"superTab":"wait-v1"`.
+ - `supertabs` and `supertab` parse every field, including `order` and an absent `since`. A malformed Lead is skipped, not the frame.
+ - A `question` carrying `superTab` calls `ui_supertab_wait`, never `ui_question_show`, and never `audio_notify_done` directly; a plain `question` is unchanged.
+ - A `question.close` whose id starts with `supertab:` calls `ui_supertab_wait_close`.
+ - `supertab.recap` with `none:true` passes `none`.
+ - Each request builds the exact JSON. `supertab.open` with an empty lead is allowed; the others refuse an empty or overlong id.
+- [ ] **Step 2: Run** `IDF_PATH=~/esp/esp-idf-5.5.4 bash test/run.sh`. Expected: the new cases FAIL.
+- [ ] **Step 3: Implement** in `cable_client.c`, the only file that builds or reads a `t`. Parse into a stack `ht_supertab_t` and hand it to the UI under its lock. On link loss, clear the Swarm model through the UI. Note the frames in `cable_client.h`'s comment block (the round dial has no separate cable document on main; the header names `docs/specs/cable-protocol.md`, which does not exist in this repository).
+- [ ] **Step 4: Run** the same command. Expected: PASS.
+- [ ] **Step 5: Commit** `feat(dial): hear the Swarms, their Leads and Super Tab waits`.
+
+### Task 4: Round firmware — Swarms in TABS (1a–1d)
+
+**Files:**
+- Modify: `devices/harness-device/firmware/main/ui/habitat/ui_habitat.c` (`ui_swarms_replace`, `tab_label`, `render_focus_tabs`, `tabs_open`, `A_TAB`/`A_TAB_DONE` in `dispatch`, `workspace_index` callers; state `s` gains the model and `swarm_mode` with the current Swarm id)
+- Test: `devices/harness-device/firmware/test/test_touch_ui.py`
+
+**Interfaces:**
+- Consumes: `ht_supertabs_for_desk`, `ht_supertabs_find`, `cable_client_supertab_send` (Tasks 2–3).
+- Produces: one tab list made of desk tabs (≤24) followed by Swarms with an empty `tab` (≤16). Entering a Swarm sets the dial's Swarm mode with no workspace handshake.
+
+- [ ] **Step 1: Write failing tests:**
+ - A desk tab linked to a Swarm keeps its place and name; it is listed even with `agents` 0.
+ - Two unopened Swarms follow the desk tabs in `supertabs` order.
+ - Every tab run uses the same font and ink as an ordinary tab (decision 1: compare against a desk tab run).
+ - Tap or ✓ on a Swarm enters it with no `swarm.select` sent and no "Switching tab" view, sending `supertab.select` then `supertab.open` for the first Lead by `order`, or for the Lead `supertab.focus` named.
+ - An ordinary desk tab still sends `swarm.select`.
+ - Hold on a Swarm face opens TABS on that Swarm.
+ - Portraits `swarm-tabs-1a` … `swarm-tabs-1d`.
+- [ ] **Step 2: Run** `python3 test/test_touch_ui.py`. Expected: FAIL.
+- [ ] **Step 3: Implement.** Keep `s.tabs` for desk tabs. Build the carousel's index space as desk tabs followed by unopened Swarms. `tab_label` returns the Swarm's name for the second part.
+- [ ] **Step 4: Run** `bash test/run.sh`. Expected: PASS. Render with `HABITAT_PREVIEW_DIR=/tmp/round-swarm python3 test/test_touch_ui.py` and compare 1a–1d with the mockup.
+- [ ] **Step 5: Commit** `feat(dial): Swarms in the tab list`.
+
+### Task 5: Round firmware — Swarm panes, PANES and following (2a–2h, 3a–3c)
+
+**Files:**
+- Modify: `devices/harness-device/firmware/main/ui/habitat/ui_habitat.c` (`render_home` face building for a Swarm pane; `render_focus_panes`/`pane_label`; `habitat_touch` horizontal swipe; `A_AGENT`/`A_AGENTS`; `ui_boot_pressed`; the recap retry on the existing timer tick)
+- Test: `devices/harness-device/firmware/test/test_touch_ui.py`
+
+**Interfaces:**
+- Consumes: Tasks 2–4; `ht_focus_face` with `ht_character_face_t` fields `name`, `engine`, `elapsed`, `mood`, `asking` and the recap text.
+- Produces: a Swarm pane index in place of `s.active` while in Swarm mode. No Lead id ever reaches `cable_client_send_focus`/`cable_client_send_open`.
+
+- [ ] **Step 1: Write failing tests.** Each face case below follows the spec §4 table:
+ - **Faces:**
+ - work local with `since` 134 → elapsed text "2:14" on the lower arc (2a);
+ - done with a recap → the card at ≤4 lines with a final "…" for a 1,500-byte text (2b, 2g);
+ - ask local with an open wait → the wait text in the card and the asking pose (2c);
+ - stuck → "Stuck: …" and no red ink (2d);
+ - work remote → "Working..." and no time (2e);
+ - ask remote → the recap card (2e′);
+ - recap none → the resting face (2f);
+ - no Leads → "No panes in this tab." and "Choose a tab" → TABS (2h).
+ - **Swipe and recap:**
+ - a horizontal swipe moves by `order` with wrap, and sends `supertab.select`, `supertab.open`, `supertab.recap.get` (no `focus`);
+ - a `supertab.recap` for another Lead is ignored;
+ - with no answer in 5 s, one more `recap.get` goes out.
+ - **PANES:** one page per Lead in `order`; a long name splits over two lines with "…"; 12 pages; ✓ picks (3a–3c).
+ - **Follow:**
+ - `supertab.focus` moves the face, except during voice;
+ - a new `supertab` without the shown Lead moves to the same position;
+ - the Swarm leaving `supertabs` → TABS.
+ - **Leaving and side button:**
+ - leaving the Swarm sends `supertab.open` with `lead:""`;
+ - the side button on a busy local Lead opens STOP for `local`; on a remote Lead it goes HOME.
+ - **Portraits:** `swarm-2a` … `swarm-2h`, `swarm-3a` … `swarm-3c`.
+- [ ] **Step 2: Run** `python3 test/test_touch_ui.py`. Expected: FAIL.
+- [ ] **Step 3: Implement.** Build an `ht_character_face_t` from the Lead (no new drawing code), with elapsed = `since_s` + (now − `since_at_ms`)/1000 and `asking` for ask/stuck. The card text priority is wait text > recap > none.
+- [ ] **Step 4: Run** `bash test/run.sh`. Expected: PASS. Render the portraits and compare with mockup 2a–3c.
+- [ ] **Step 5: Commit** `feat(dial): a Swarm's projects as panes`.
+
+### Task 6: Round firmware — beep and inbox (4a–4f, 2e′)
+
+**Files:**
+- Modify: `devices/harness-device/firmware/main/ui/habitat/ui_habitat.c` (`ui_supertab`/`ui_supertab_wait`/`ui_supertab_wait_close` → `notice_add`/`notice_remove`; `ui_notif_replace` re-merging dial-owned entries; `render_focus_inbox`/`render_notice` grey line from the Swarm name; `A_NOTICE` for a Swarm entry), `devices/harness-device/firmware/main/cable_client.c` (`audio_notify_done` when the UI reports a raised entry not on the face, as the `question` handler does today)
+- Test: `devices/harness-device/firmware/test/test_touch_ui.py`, `devices/harness-device/firmware/test/test_question_ui.py`, `devices/harness-device/firmware/test/test_cable_identity.py`
+
+**Interfaces:**
+- Consumes: the `ht_lead_event_t` transitions (Task 2) and the wait entry points (Task 3).
+- Produces: one question-type notice per Lead, keyed by the Lead's agent id, with an owner flag of "dial" so `ui_notif_replace` keeps it.
+
+- [ ] **Step 1: Write failing tests:**
+ - **Raise and clear:**
+ - a remote Lead going done→ask adds "Needs you. Answer on the desktop." with the Swarm's name on the grey line and the project in green, and beeps once (4e);
+ - stuck adds "Stuck. See the desktop.";
+ - back to work removes it.
+ - **Local waits:**
+ - a local Lead's wait replaces the text with `questions[0].q` (4c, 4d);
+ - the wait and the state change, in either order, give one entry and one beep;
+ - `question.close` restores the fixed text while still ask;
+ - a Super Tab wait never opens QUESTION/CHOICE/ANSWER_REVIEW (`test_question_ui.py`);
+ - a wait from an agent that is no Lead's `local` adds nothing.
+ - **Inbox behaviour:**
+ - a `notif.replace` with desktop rows keeps every Swarm entry;
+ - an entry for the Lead on the face is read at once, with no beep;
+ - the bell pill shows the count at y 400, or the pet's bubble while working (4a, 4b);
+ - tapping a Swarm entry enters that Swarm at that Lead;
+ - link loss clears the Swarm entries;
+ - an empty inbox shows "No notification" (4f).
+ - **Portraits:** `swarm-4a` … `swarm-4f`, `swarm-2e-ask`.
+- [ ] **Step 2: Run** `python3 test/test_touch_ui.py && python3 test/test_question_ui.py`, then `IDF_PATH=~/esp/esp-idf-5.5.4 python3 test/test_cable_identity.py`. Expected: FAIL.
+- [ ] **Step 3: Implement.** Reuse `notice_add`, `notice_remove`, `notice_read_now` and `on_face`. Mark Swarm notices so `ui_notif_replace` re-adds them after rebuilding from the snapshot.
+- [ ] **Step 4: Run** `bash test/run.sh` (with `IDF_PATH`). Expected: PASS.
+- [ ] **Step 5: Commit** `feat(dial): a Lead that needs you beeps and waits in the inbox`.
+
+### Task 7: Round firmware — talk to a local Lead (5a–5e)
+
+**Files:**
+- Modify: `devices/harness-device/firmware/main/ui/habitat/ui_habitat.c` (the face tap → `A_VOICE` target and `s.voice_engine` while in Swarm mode)
+- Test: `devices/harness-device/firmware/test/test_voice_ui.py`, `devices/harness-device/firmware/test/test_touch_ui.py`
+
+**Interfaces:**
+- Consumes: `ht_lead_t.local` and `engine`.
+
+- [ ] **Step 1: Write failing tests:**
+ - a tap on a local Lead's face starts voice with `agent_id` = `local` (never the Lead id), shows listening and sending, then returns to the Swarm face (5a–5d);
+ - an engine with no listening scene shows the seven bars (5e);
+ - a tap on a remote Lead's face starts nothing.
+ - Portraits `swarm-5a` … `swarm-5e`.
+- [ ] **Step 2: Run** `python3 test/test_voice_ui.py && python3 test/test_touch_ui.py`. Expected: FAIL.
+- [ ] **Step 3: Implement.**
+- [ ] **Step 4: Run** `bash test/run.sh`. Expected: PASS.
+- [ ] **Step 5: Commit** `feat(dial): talk to a Swarm's Lead on this computer`.
+
+### Task 8: Build, renders against the mockup, real device
+
+- [ ] **Step 1:** `cd devices/harness-device/firmware && . ~/esp/esp-idf-5.5.4/export.sh && idf.py -B build -DPROJECT_VER=0.0.99 build`. Expected: the image fits its OTA slot. Record the size against `main` (PSRAM model ≈ 54 KB; no internal-RAM growth expected; check `ram_telemetry` in the alive log).
+- [ ] **Step 2:** Render every portrait with `HABITAT_PREVIEW_DIR`. Check by script that no pixel brighter than 16 lies outside r 233 (the mockup's check). Compare all 27 screens side by side with the mockup, and list each difference in the PR.
+- [ ] **Step 3:** Independent code review of the whole branch by a fresh reviewer; fix the findings, each with a test.
+- [ ] **Step 4 (owner's go-ahead):**
+ - `make install-cli` from the branch;
+ - flash the 0.0.99 build on one round dial (`idf.py -p PORT flash`, README "Build and flash your board"; quit the monitor before the app reconnects);
+ - with the "openharness" Swarm, check TABS, an unopened Swarm, swipes, PANES, a remote Lead's beep and entry, a local Lead's wait, talk, follow-the-desktop, and the side button.
+- [ ] **Step 5 (owner's go-ahead):** commit, push, open the PR listing every check below and the device check.
+
+## Validation (docs/validation-and-release.md)
+
+- **PR CI** (automatic): `cli-typecheck` + `cli-tests` for `cli/`; `firmware-checks` for `devices/` (every `test_*.py` plus `run.sh` on Linux with clang-18 and the SDK's cJSON); `pro-firmware-build` + `pro-golden` because Task 1 touches `devices/harness-pro/` (a test and a doc only; the golden diff must be empty).
+- **Local, recorded in the PR:**
+ - `npx vitest run src/superTabs src/cable` and `npm run typecheck`;
+ - `bash test/run.sh` with `IDF_PATH` set (the cJSON tests run only then);
+ - the IDF build;
+ - the Pro's `bash test/run.sh`.
+ - Not needed: `test:core` (no `src/core`/`src/services` change), CLI e2e (no CLI user flow changes), the OS workflows.
+- **Not covered by any automatic check:** the 27 renders against the mockup (by eye) and the real device. Say so in the PR.
+
+## Rollout
+
+1. **CLI first.** The CLI release carries `order`. The firmware works with a CLI from #1537 on, but the panes come in urgency order until this one lands. An older dial is unaffected: it names neither capability.
+2. **Firmware next:** `make upload-circle` (`devices/harness-device/firmware/RELEASE.md`). Daemons offer it over the cable from the published manifest (`cli/src/cable/fwPush.ts`, key `commander`). Choose the version above the published one: `version.txt` on main reads 0.0.86, but 0.0.92 was reported published on 2026-10-20, so read the manifest first.
+3. **Pro:** nothing to release. Its firmware ignores `order`.
+4. **Rollback:** republish the previous round image. The daemon change is additive.
+
+## Open risks
+
+- **The `order` field's value.** The Pro already sorts Leads on the device (`ph_overview.c` `lead_order`), so sending Leads in project order would have served both dials without a new field. The owner chose `order`, so this plan uses it.
+- **Worker waits.** A Super Tab wait from a worker on this machine adds no entry of its own; it surfaces through its project's Lead (spec §5). This interpretation needs the owner's confirmation.
+- **Recap loading.** The face shows no card while a recap loads; the mockup has no screen for that moment.
+- **State lag.** Lead states come from the daemon's 5 s backend poll, so a beep can trail the desktop by up to about 5 s plus the 300 ms debounce.
+- **Unverified items** in the spec's "Unverified" section:
+ - voice to a harness outside the dial's roster;
+ - `dial_super_tab` for a Swarm never opened on the desktop;
+ - a Swarm desk tab reporting 0 agents.
diff --git a/docs/superpowers/specs/2026-10-23-round-swarm-tab-design.md b/docs/superpowers/specs/2026-10-23-round-swarm-tab-design.md
new file mode 100644
index 000000000..5a863f4ff
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-23-round-swarm-tab-design.md
@@ -0,0 +1,330 @@
+# Round dial: the Swarm tab
+
+Status: design from the owner-approved mockup and the owner's decisions (2026-10-23). Mockup:
+`devices/harness-device/mockup/round-swarm/index.html` (gitignored, main checkout; 27 screens rendered by the Round firmware
+code at 669e65df9, which is identical to the firmware on origin/main f67349146). Builds on the Harness Pro Swarm card
+(#1537, #1548; `docs/plans/2026-10-22-pro-swarm-card-design.md`), whose daemon side and cable frames this reuses.
+
+## Problem
+
+A Swarm reaches the round dial only as an ordinary desktop tab. The desktop reports that tab's terminal panes, which
+is the Lead of the selected project and nothing else. The dial cannot show the Swarm's other projects. It cannot show
+what each Lead last said, or which Lead needs a person. It never sees a Swarm the desktop has not opened, and it does
+not hear about a Lead that runs on someone else's machine. The daemon already reads all of this for the Harness Pro
+(`swarmCard: "v1"`), but the round dial does not ask for it.
+
+## Goal
+
+On the round dial, each Swarm is one more tab in the existing tab list. It looks exactly like every other tab. Inside
+it, each project of the Swarm is a pane showing that project's Lead. A swipe moves between projects as it moves
+between panes today, and the existing agent face shows the Lead's state and last message. A Lead that needs a person or
+is stuck beeps and adds one entry to the existing inbox, whether it runs on this computer or on someone else's. You can
+talk to a Lead that runs on this computer as to any pane. A Lead on another machine is read-only.
+
+Everything uses the round dial's own screens: the TABS carousel, the agent face (`ht_focus_face`), the PANES carousel,
+the inbox, the bell, the talk screens. Only the data is new.
+
+Out of scope: a Swarm home or overview screen; a Pro-style card; showing workers (Engineer/Reviewer agents) as panes;
+answering or posting to a Lead on another machine; answering a Super Tab wait on the dial; any desktop change.
+
+## Terms
+
+- **Swarm**: a Super Tab (`superTab` in the code and on the wire).
+- **Lead**: the system name of a project's coordinating agent. Its on-screen name is **Product Manager**
+ (`docs/naming-system.md`). No string on the dial names either one.
+- **Desk tab**: an ordinary desktop tab. In the round firmware this is a `swarms` frame row (`cable_swarm_t`, `s.tabs`,
+ `cable_client_select_swarm`). That old internal name stays (naming system: internal names are not renamed). Do not
+ mistake it for a Swarm.
+- **Swarm pane**: one project's Lead, shown on the dial as a pane of the Swarm tab.
+
+## Decisions (owner, mockup section 7 "Đã quyết")
+
+1. **The Swarm tab looks like any tab.** Same font and colour in TABS. No badge, capsule or colour of its own; people
+ tell it apart by its name (1a–1c).
+2. **Swarms not open on the desktop are listed too**, after the desktop's tabs (1d).
+3. **Projects keep a fixed order**: the Swarm's project order, the same as in the app, never sorted by state. Swiping
+ never jumps (2a–2h, 3a–3c).
+4. **A Lead on another machine that needs you, or is stuck, also beeps** (2e′, 4e).
+5. **No reply to a remote Lead in v1.** It is read-only on the dial; people answer on the desktop (2e, 2e′, 5e).
+6. **Leads only.** No worker agents as panes (2, 3).
+7. **The project order comes from a new `leads[i].order`.** Today the daemon sorts Leads by urgency for the Pro
+ (`cli/src/superTabs/cards.ts`). The round dial needs the original position, so the daemon adds `order`, which the
+ Pro ignores.
+8. **The inbox entry text for a remote Lead is fixed and approved**: "Needs you. Answer on the desktop." and "Stuck.
+ See the desktop." (4e).
+
+## Design
+
+### 1. Cable
+
+The round dial uses the Pro's frames exactly as they are (`cli/src/cable/cableSession.ts`, from #1537). The daemon
+needs no new frame and only one new field.
+
+**Hello.** The round dial adds two capabilities, both already defined in the daemon:
+
+- `"swarmCard":"v1"`: the daemon then sends `supertabs`, `supertab`, `supertab.recap` and `supertab.focus`, and
+ accepts `supertab.recap.get`, `supertab.open` and `supertab.select`. The first capable device makes the superTabs
+ service start its 5 s backend poll (`swarmCardsWanted`).
+- `"superTab":"wait-v1"`: the daemon then sends Super Tab waits as `question` frames carrying `superTab` (the Swarm's
+ name, ≤48 bytes) and `attention` (`"decision"` or `"stuck"`), and resends them on resync. Today the daemon holds them
+ back from a round dial because it would open an answer screen that cannot load (`cableSession.ts`, `superTabWaits`).
+ Section 5 is the rule that makes that safe.
+
+`seq` stays Pro-only (`board === 'pro'`); the round dial's frames are unchanged.
+
+**Frames the dial reads** (shapes from the Pro spec §3):
+
+```
+{"t":"supertabs","ids":["<superTabId>",...]} ≤16, desktop-open Swarms first
+{"t":"supertab","id":"<superTabId>","tab":"<desk tab id or empty>","name":"openharness","count":4,
+ "leads":[{"id":"<leadAgentId>","projectId":"…","project":"mobile","engine":"claude","owner":"",
+ "local":"<harnessId or empty>","state":"ask|stuck|work|done","since":134,"order":0}]} ≤12 Leads
+{"t":"supertab.recap","tab":"…","lead":"…","text":"…","at":1792560000,"none":false} text ≤1,500 bytes
+{"t":"supertab.focus","tab":"…","lead":"…"}
+{"t":"question","agentId":"<harnessId>","name":"…","id":"supertab:…","questions":[{"q":"…"}],
+ "superTab":"openharness","attention":"decision|stuck"}
+{"t":"question.close","agentId":"<harnessId>","id":"supertab:…"}
+```
+
+**Frames the dial sends:** `supertab.recap.get {tab, lead}`, `supertab.open {tab, lead|""}`, and
+`supertab.select {tab, lead}`. All three are constructed in `cable_client.c`, as every message is.
+
+**New field `order`** (decision 7): each Lead's 0-based position in its Swarm's project list (`state.projects`; the
+synthetic `lead` project of an older tab is 0). It is taken before the urgency sort and the cut to 12. When a Swarm has
+more than 12 projects, the 12 sent are still the most urgent ones, so `order` can have gaps; the dial sorts by it and
+ignores the gaps. The cost is 2 JSON tokens per Lead: 24 more for a 12-Lead frame, measured under 260 tokens today and
+under the 512-token guard on both dials. The Pro reads Lead fields by name (`pro_cable.c` `read_leads`), so it ignores
+`order`. On a frame without `order` (a daemon from before this change), the dial keeps the frame's order.
+
+**Data per screen** (mockup section 6):
+
+| Screen | Data | On the wire today? |
+| --- | --- | --- |
+| 1a–1c Swarm in TABS | `swarms` rows (desk tabs) + `supertab.tab` linking a Swarm to its desk tab | Yes |
+| 1d Swarm not open | `supertabs.ids` + `supertab.tab:""` | Yes; firmware rule (§3) |
+| 2a–2h Swarm pane | `supertab.leads[i]` {project, engine, owner, local, state, since} | Yes |
+| 2, 3 Fixed order | `leads[i].order` | **New** (daemon) |
+| 2 Recap card | `supertab.recap` ← `supertab.recap.get`, pushed for the Lead named by `supertab.open` | Yes |
+| 2 swipe, 3 PANES pick | `supertab.select` then `supertab.open`; `supertab.focus` when the desktop moves | Yes |
+| 2c, 2d, 4 local Lead waits | `question` with `superTab`/`attention`, `question.close` | Yes, behind `wait-v1` |
+| 2e′, 4e remote Lead | `leads[i].state` ask/stuck with `local:""`; card = `supertab.recap` | Yes; firmware rule (§5) |
+| 5 Talk | `leads[i].local` → existing voice path | Yes |
+
+### 2. Firmware model (new `supertab` module)
+
+A pure module, `main/ui/habitat/supertab.c/.h`, in the style of `workspace.c` and `visit.c`, with no LVGL and no cable
+code, tested on the host. It holds:
+
+- the Swarm id list (≤16) and one record per Swarm: `id`, `tab` (desk tab id or empty), `name` (≤48 bytes + NUL),
+ `count`, and Leads (≤12), sorted by `order` and stable on ties. Each Lead record holds `id`, `project_id`, `project`,
+ `engine`, `owner`, `local`, `state`, `since_s` plus the dial clock at receipt, and the previous `state` (for §5);
+- one recap slot: the open Lead's text (≤1,500 bytes + NUL), its `at`, and a flag for none, loading or loaded. The
+ slot belongs only to the Swarm pane on the face (mockup: "only the open project's recap"; the Pro also drops
+ recaps on close);
+- the transition events in §5: entered ask, entered stuck, left ask/stuck, and Lead gone.
+
+It lives in PSRAM (`EXT_RAM_BSS_ATTR`, like the UI state `s`). The worst case is 16 × 12 Leads × about 280 bytes,
+about 54 KB, plus one 1.5 KB recap. A `supertab` frame for an id not in the last `supertabs` list is dropped. A
+`supertabs` list drops the records whose ids left it.
+
+### 3. TABS (screens 1a–1d)
+
+The TABS carousel lists, in order:
+
+1. The desk tabs, as today, from `swarms`. A desk tab linked to a Swarm (some Swarm's `tab` equals its id) stays at its
+ desk position and keeps its name. It is listed even when its `agents` is 0 (today `ui_swarms_replace` hides such a
+ tab; a Swarm tab whose selected project's Lead runs elsewhere may report 0).
+2. Then every Swarm whose `tab` is empty, in `supertabs.ids` order (1d), drawn with the Swarm's `name`.
+
+Every entry uses the same `tab_name`/`tab_split` drawing, the same ink and the same fade (decision 1). The list can
+hold 24 desk tabs + 16 Swarms; the carousel takes the count and needs no paging.
+
+Opening a tab (tap on its name, or ✓):
+
+- **Ordinary desk tab:** unchanged (`tab_request` → `cable_client_select_swarm`, workspace handshake).
+- **Swarm, open on the desktop or not:** entered locally, with no workspace handshake, because the dial already has
+ the Swarm's data. The face shows the Swarm's current pane (§4: the Lead the desktop has open if `supertab.focus`
+ named one, else the first by `order`). The dial sends `supertab.select` for that Lead, then `supertab.open`.
+ `supertab.select` makes the desktop focus or reopen that Swarm tab at that project (`dial_super_tab`, desktop
+ `app_state.dart`); with no desktop window it does nothing.
+
+Hold on the face still opens TABS (`tabs_open`); the carousel opens on the current tab or Swarm.
+
+### 4. Inside a Swarm tab (screens 2a–2h, 3a–3c)
+
+While the dial is in a Swarm tab, its panes are that Swarm's Leads in `order`, not the desk roster (`s.agents`). A
+desk roster that arrives for the linked desk tab (the Lead's terminal pane) does not replace them. Decision 6: one
+pane per project, no workers.
+
+**The face** is the existing agent face (`render_home` → `ht_focus_face`), built from the Lead:
+
+| Lead | Upper arc | Middle | Card / lower arc | Mockup |
+| --- | --- | --- | --- | --- |
+| `work`, local (`since` set) | project | engine pet, working scene | elapsed from `since` + dial time since receipt, on the lower arc | 2a |
+| `work`, remote (no `since`) | project | pet, or the engine's 56 px mark when the engine has no pet | "Working..." with no time | 2e |
+| `done` | project | pet | recap card: Lead's last message, ≤4 lines then "…", pet shrinks | 2b, 2g |
+| `done`, recap `none` | project | resting face | existing one-line hint | 2f |
+| `ask`, local with an open wait | project | pet in asking pose | wait text (`questions[0].q`) in the recap's place | 2c |
+| `stuck`, local with an open wait | project | pet in asking pose, no red | "Stuck: …" text from the daemon | 2d |
+| `ask`/`stuck`, remote (or local without a wait) | project | pet in asking pose | recap card (last message) | 2e′ |
+| no Leads | — | "No panes in this tab." + "Choose a tab" (→ TABS) | — | 2h |
+
+The upper-arc name is cut on the arc like every pane name (2b). Text that cannot be drawn in Inter goes through the
+existing `ui_can_display` checks.
+
+**Recap.** When a Swarm pane comes onto the face (entering, swipe, PANES pick, follow), the dial sends
+`supertab.recap.get` and `supertab.open` for it and clears the recap slot. Until the text arrives, the face draws the
+state without a card: the working line for `work`, the resting face otherwise. (Not in the mockup.) If no answer
+arrives within 5 s, the dial asks once more; the daemon ignores a repeat within 1 s. A `supertab.recap` for any other
+Lead is dropped. Leaving the Swarm tab, or the face leaving for another tab, sends `supertab.open` with `lead:""`.
+
+**Swipe.** A horizontal swipe on the face moves to the next or previous project, as on panes today (`habitat_touch`,
+including the wrap at the ends). It sends `supertab.select` + `supertab.open` + `supertab.recap.get`, and never
+`focus` or `agent.open`: a Lead id is not a cable agent id.
+
+**PANES** (tap on the upper-arc name; 3a–3c): the existing `render_focus_panes` carousel. One page per Lead in `order`
+(`pane_label` = project). Long names split over two lines with "…" (`tab_split`, 3b). It opens on the current project.
+✓ or a tap on a name picks one, same messages as a swipe. Up to 12 pages, with no paging dots (3c).
+
+**Following the desktop.** `supertab.focus {tab, lead}`: when the dial is in that Swarm tab, the face moves to that
+Lead (same rules as `focus` today: not while talking, not in a question or form view). When the dial is in that
+Swarm's linked desk tab because the desktop selected it, the dial enters the Swarm at that Lead. Otherwise the dial
+remembers the Lead as the Swarm's current pane for the next time it is entered. The daemon already suppresses the echo
+of the dial's own pick (`picked`, `PICK_ECHO_MS`).
+
+**Changes while you watch.** A new `supertab` keeps the face on the same Lead id. If that Lead is gone, the face moves
+to the Lead now at the same position, or shows 2h if none are left. If the Swarm leaves `supertabs`, the dial returns
+to TABS.
+
+### 5. Needs you / stuck: beep and inbox (screens 4a–4f, 2e′)
+
+There is no toast. A Lead entering `ask` or `stuck` gets the existing alert path: a beep (`audio_notify_done`, at most
+one per 30 s), a display wake, and one inbox entry. The face changes only as it does today: the green bell pill at
+y 400 with the unread count, or the pet's bell bubble while the pet is working (4a, 4b). Pull down from the face, or tap
+the bell, opens the inbox (`render_focus_inbox`).
+
+Rules, for every Lead of every Swarm in `supertabs` (on this machine or not):
+
+- **One entry per Lead**, keyed by the Lead's agent id. It is a question-type entry, so it sorts before recaps and
+ never expires after 6 h.
+- **The trigger is the Lead's `state`.** A change from anything else (including not yet seen) to `ask` or `stuck`
+ adds the entry and beeps (decision 4). The text is fixed: "Needs you. Answer on the desktop." or "Stuck. See the
+ desktop." (decision 8). A change back to `work`/`done`, or the Lead leaving the list, removes the entry.
+- **Wait text for a Lead on this machine.** A `question` frame with `superTab` whose `agentId` equals some Lead's
+ `local` replaces that Lead's entry text with `questions[0].q` and makes the Lead's face show it (2c, 2d). It never
+ opens the question or answer screen: `ui_question_show` is not called for it. Its `question.close` reverts the text
+ to the fixed text while the Lead is still `ask`/`stuck`. Since the entry is one per Lead and the beep is coalesced,
+ a wait arriving before or after the state change beeps once (mockup: "no double beep").
+- **A Super Tab wait from a non-Lead** (a worker on this machine) adds no entry of its own (decision 6). The project's
+ Lead already reads `ask`/`stuck` from the same assignment, which raises the Lead's entry. *(Interpretation of
+ decision 6 for the inbox; confirm.)*
+- **On the face:** an entry for the Lead on the face is read at once and does not beep (the existing `on_face` rule).
+- **Survives `notif.replace`.** The desktop's inbox snapshot replaces the desktop rows only. The dial's Swarm entries
+ are kept and re-merged (today `ui_notif_replace` rebuilds `s.notice` from the snapshot alone, which would drop
+ them).
+
+**The entry card** (4c–4e): grey top line = the Swarm's name (the wait's `superTab`, else the Swarm record's name), in
+the seat where `machine` goes today. Green line = engine mark + project. Body = the wait text or the fixed text.
+Swipe pages through entries as today. Tapping the entry enters that Swarm at that Lead (§3 entry path), so the face
+shows 2c / 2d / 2e′ instead of the agent open path. 4f "No notification" is the existing empty inbox.
+
+### 6. Talk (screens 5a–5e)
+
+A tap on the face of a Lead with `local` talks to it exactly as to any pane: the existing listening, sending and back
+flow, with `cable_client_voice_begin(local, …)` (5a–5d). An engine without a listening scene uses the seven bars (5e).
+After sending, the face returns to the working state from the next `supertab` (the daemon reads a local Lead's live
+turn when it builds the cards). A Lead without `local` (remote) has no talk: a tap on its face does nothing, and there
+is no reply path in v1 (decision 5).
+
+### 7. Interactions
+
+| Input | Desk tab (today) | Swarm tab |
+| --- | --- | --- |
+| Tap face | talk to the pane | talk to a local Lead; nothing on a remote Lead |
+| Tap upper-arc name | PANES | PANES of the Swarm's projects |
+| Hold face | TABS | TABS |
+| Horizontal swipe on face | next/previous pane, `focus` | next/previous project, `supertab.select` + `open` + `recap.get` |
+| Pull down / tap bell | inbox | inbox |
+| Tap inbox entry | open that agent | enter that Swarm at that Lead |
+| Side button (BOOT) tap | stop a busy pane's turn (STOP), cancel voice, else HOME | stop a busy **local** Lead (STOP on `local`); cancel voice; else HOME. No stop for a remote Lead |
+| Side button hold | screen on/off | screen on/off |
+
+### 8. Daemon
+
+- `cli/src/superTabs/cards.ts`: `SwarmLead.order` (§1), set in `leadsOf` before the sort. The leading comment that
+ says "in project order then by urgency" is wrong today (the code sorts by urgency first) and is corrected.
+- `cli/src/cable/cableSession.ts` `pushSwarmCards`: `order` copied onto each Lead of the `supertab` frame.
+- Nothing else. The round dial gets every other frame by naming the capabilities. The service, core bridge, devices
+ service and desktop are unchanged.
+- `devices/harness-pro/docs/cable.md`: `order` documented as optional and ignored by the Pro.
+
+## Errors and edge cases
+
+- **Daemon without `order`:** the dial keeps the frame order (urgency). Usable, but it jumps; the release notes say
+ to update the CLI first.
+- **Daemon from before #1537:** it sends no `supertab*` frames. The TABS list has only desk tabs, and a Swarm's desk
+ tab behaves as today.
+- **No desktop window:** desk tabs are empty. Swarms from the backend are still listed (all at the end), and
+ `supertab.select` is harmless.
+- **Signed out / backend unreachable:** the daemon keeps the last cards (Pro spec). The dial shows what it last
+ received.
+- **Reconnect:** the dial clears the Swarm model and its Swarm inbox entries on link loss. On attach, the daemon
+ resends all cards (force) and every open wait, and the transitions re-raise entries. The beep coalesce holds a
+ burst of re-raised entries to one beep.
+- **More than 12 projects:** 12 panes (the most urgent, then sorted by `order`). `count` carries the real number; the
+ dial does not show it.
+- **Malformed Lead:** skipped, not the frame (as on the Pro). An unknown `state` reads as `done`.
+- **A desk tab linked to a Swarm whose `supertab` has not arrived yet:** it behaves as an ordinary desk tab until it
+ does.
+
+## Testing
+
+- **CLI:** `cards.spec.ts` (`order` = project position, kept through the urgency sort and the cut; old tab → 0);
+ `cableSession.spec.ts` (a round hello with `swarmCard:"v1"` and `superTab:"wait-v1"` gets `supertab*` frames without
+ `seq`, and waits; `order` on every Lead; a 16×12 frame under 512 tokens).
+- **Pro firmware:** `test_pro_cable.c`, a Lead with `order` parses the same as one without.
+- **Round firmware, host:** a new `test_supertab.c` (model, order, caps, transitions, recap slot); cable handlers with
+ real cJSON in `test_cable_identity.py` (needs `IDF_PATH`); `test_touch_ui.py` scenes and portraits for every mockup
+ screen (TABS, faces, PANES, inbox, talk), each scanned for Inter-only text and ink inside r 230;
+ `test_question_ui.py` (a Super Tab wait never opens the question screen); `test_voice_ui.py` (local Lead talks,
+ remote does not).
+- **Renders:** the round dial has no checked-in pixel goldens (the Pro's `golden.sh`). Its renders are
+ `HABITAT_PREVIEW_DIR` portraits (PPM + JSON spec) from `test_touch_ui.py`, compared by eye with the mockup, plus scene
+ assertions in the test itself.
+- **Device:** a dev build (`-DPROJECT_VER=0.0.99`) on a round dial with a dev CLI, against the "openharness" Swarm.
+
+## Screen → section map
+
+| Mockup | Section |
+| --- | --- |
+| 1a, 1b, 1c | §3 TABS, decision 1 |
+| 1d | §3 item 2, decision 2 |
+| 2a | §4 face (work, local) |
+| 2b, 2g | §4 face (done, recap), §2 recap slot |
+| 2c | §4 face (ask, local), §5 wait text |
+| 2d | §4 face (stuck, local), §5 |
+| 2e | §4 face (work, remote), §6 no talk, decision 5 |
+| 2e′ | §4 face (ask, remote), §5, decision 4 |
+| 2f | §4 face (none) |
+| 2h | §4 face (no Leads) |
+| 3a, 3b, 3c | §4 PANES, decision 3 |
+| 4a, 4b | §5 bell / pet bubble |
+| 4c, 4d | §5 entry card, wait text |
+| 4e | §5 remote rule, decision 8 |
+| 4f | §5 (existing empty inbox) |
+| 5a–5d | §6 talk |
+| 5e | §6 bars; remote Lead has no talk |
+| Section 6 (cable data) | §1 |
+| Section 7 (decisions) | Decisions 1–8 |
+
+## Unverified
+
+- The voice router accepts `voice.begin` for a local Lead's harness id when that harness is not in the dial's current
+ roster (a Swarm's desk tab may not hold it). This is expected, since voice is routed by `agentId` in the daemon, but
+ it has not been tested.
+- `dial_super_tab` reopening a Swarm that the desktop has never opened (Pro spec §5 says "focus (or reopen)"). This
+ has not been checked against the desktop code on main.
+- What a Swarm desk tab reports as `agents` when its selected project's Lead runs on another machine. The spec
+ defensively lists linked desk tabs with 0 agents.
+- The published round firmware version. `version.txt` on main reads 0.0.86, but 0.0.92 was reported published on
+ 2026-10-20. Check the GCS manifest before choosing the release version.