@gperezmz/bb-plugin-thread-glance 0.1.3 → 0.2.1

package/features/thread-list/model/families.ts

@@ -12,13 +12,13 @@ import {
   type StateKind,
   type ThreadState,
 } from "./state";
-import { attentionFlagsOf, isOrphanedFailure } from "./attention";
+import { needsYouFlagsOf, isOrphanedFailure } from "./needs-you";
 import { compareCreationAscending } from "./sort";
 import { needsKindOf, rowNote, type RowNote } from "./notes";
 import type { ThreadNotes } from "@/shared/contract";
 import type { ChildAttention } from "@/shared/preferences";
 
-/** States that keep a child out of its family's fold with `childAttention` `blocked`: working, setting up, background work. */
+/** States that keep a child out of its family's older fold with `childAttention` `blocked`: working, setting up, background work. */
 const RUNNING: ReadonlySet<StateKind> = new Set<StateKind>(["working", "background"]);
 
 /** Everything the list knows about one thread. */
@@ -26,24 +26,24 @@ export interface ThreadInfo {
   thread: PluginSidebarThread;
   state: ThreadState;
   unread: boolean;
-  /** Own flags; for hidden threads only needs-you and unread-failed. */
+  /** Own flags; for hidden threads only waits-on-you and unread-failed. */
   flags: ReadonlySet<Flag>;
   /**
-   * The flags of this thread that count towards Needs attention, its
+   * The flags of this thread that make it need you, for Needs you, the
    * counters and auto-reveal: a child counts less than a root.
    */
-  attention: Set<Flag>;
+  needsYou: Set<Flag>;
   /** Quiet test for the thread alone. */
   quiet: boolean;
   /**
-   * Nothing to see behind a family's fold. A root, or any child when
-   * `childAttention` is `everything`: the quiet test without the open
-   * thread's exemption. Otherwise a child is settled unless it runs or
-   * counts towards Needs attention, so finishing unread folds it; an
-   * archived child is always settled. The fold
-   * reads this, so opening a thread never changes which children stay shown.
+   * A quiet thread, as if no thread were open: nothing to see behind a
+   * family's fold. A root, or any child when `childAttention` is
+   * `everything`, takes the quiet test without the open thread's exemption.
+   * Otherwise a child is quiet unless it runs or needs you, so finishing
+   * unread folds it; an archived child is always quiet. The fold reads this,
+   * so opening a thread never changes which children stay shown.
    */
-  settled: boolean;
+  quietIgnoringOpen: boolean;
   isActive: boolean;
   /** The visible ancestor it attaches to, or null for a root. */
   parentId: string | null;
@@ -55,35 +55,35 @@ export interface ThreadInfo {
 export interface Subtree {
   /** Descendants, depth-first in creation order, hidden ones included. */
   descendants: ThreadInfo[];
-  /** Union of the descendants' attention flags and working, archived ones left out. */
+  /** Union of the descendants' Needs you flags and working, archived ones left out. */
   flags: ReadonlySet<Flag>;
   /** Visible descendants: the chip's number. */
   visibleCount: number;
-  /** Every visible descendant is settled, so the subtree adds nothing to see when folded. */
-  settled: boolean;
+  /** Every visible descendant is quiet, as if no thread were open, so the subtree adds nothing to see when folded. */
+  quietIgnoringOpen: boolean;
 }
 
 export interface Family {
   root: ThreadInfo;
   /** Descendants, depth-first in creation order, hidden ones included. */
   descendants: ThreadInfo[];
-  /** Union of the descendants' attention flags and working (the chip rollup). */
+  /** Union of the descendants' Needs you flags and working (the chip rollup). */
   descendantFlags: ReadonlySet<Flag>;
   /** The same over root and descendants (rollup, folder rows). */
   flags: ReadonlySet<Flag>;
-  /** Attention flags over root and descendants: what the filter and the urgency order read. */
-  attentionFlags: ReadonlySet<Flag>;
+  /** Needs you flags over root and descendants: what the section and its order read. */
+  needsYouFlags: ReadonlySet<Flag>;
   /** Visible descendants: the chip's number. */
   visibleDescendantCount: number;
   /** Largest latestAttentionAt over the family. */
-  attention: number;
+  latestAttentionAt: number;
   /** Every thread quiet and the active thread not in it. */
   quiet: boolean;
   /**
    * The quiet test without the open thread's exemption. A group's fold reads
    * this, so opening a thread never changes which roots stay shown.
    */
-  settled: boolean;
+  quietIgnoringOpen: boolean;
   containsActive: boolean;
 }
 
@@ -104,7 +104,7 @@ export interface ForestInputs extends ThreadContext {
   now: number;
   /** Server notes per thread id; absent until loaded. */
   notes?: Readonly<Record<string, ThreadNotes>>;
-  /** Which children count towards Needs attention; `blocked` when absent. */
+  /** Which children can need you; `blocked` when absent. */
   childAttention?: ChildAttention;
 }
 
@@ -159,9 +159,9 @@ export function buildForest(inputs: ForestInputs): Forest {
       state,
       unread,
       flags: thread.isHidden ? hiddenThreadFlags(flags) : flags,
-      attention: new Set<Flag>(),
+      needsYou: new Set<Flag>(),
       quiet: isQuietThread(state, unread, isActive),
-      settled: false,
+      quietIgnoringOpen: false,
       isActive,
       parentId: attachParent(thread, byId),
       note: rowNote(thread, inputs.notes?.[thread.id]),
@@ -170,18 +170,18 @@ export function buildForest(inputs: ForestInputs): Forest {
 
   const mode = inputs.childAttention ?? "blocked";
   for (const info of infos.values()) {
-    const manager = info.parentId === null ? undefined : infos.get(info.parentId);
-    info.attention = attentionFlagsOf(info.flags, {
-      isRoot: manager === undefined,
+    const parent = info.parentId === null ? undefined : infos.get(info.parentId);
+    info.needsYou = needsYouFlagsOf(info.flags, {
+      isRoot: parent === undefined,
       mode,
       orphaned:
-        manager !== undefined &&
-        isOrphanedFailure(info.thread, info.flags, { ...manager, finishedAt: inputs.finishedAt[manager.thread.id] }),
+        parent !== undefined &&
+        isOrphanedFailure(info.thread, info.flags, { ...parent, finishedAt: inputs.finishedAt[parent.thread.id] }),
     });
-    info.settled =
-      manager === undefined || mode === "everything"
+    info.quietIgnoringOpen =
+      parent === undefined || mode === "everything"
         ? isQuietThread(info.state, info.unread, false)
-        : info.thread.isArchived || (!RUNNING.has(info.state.kind) && info.attention.size === 0);
+        : info.thread.isArchived || (!RUNNING.has(info.state.kind) && info.needsYou.size === 0);
   }
 
   const children = new Map<string, string[]>();
@@ -208,7 +208,7 @@ export function buildForest(inputs: ForestInputs): Forest {
     const descendants: ThreadInfo[] = [];
     const flags = new Set<Flag>();
     let visibleCount = 0;
-    let settled = true;
+    let quietIgnoringOpen = true;
     path.add(id);
     for (const childId of children.get(id) ?? []) {
       if (path.has(childId)) continue;
@@ -216,17 +216,17 @@ export function buildForest(inputs: ForestInputs): Forest {
       const below = subtreeOf(childId, path);
       descendants.push(child, ...below.descendants);
       if (!child.thread.isArchived) {
-        for (const flag of child.attention) flags.add(flag);
+        for (const flag of child.needsYou) flags.add(flag);
         if (child.flags.has("working")) flags.add("working");
       }
       for (const flag of below.flags) flags.add(flag);
-      if (child.thread.isHidden ? child.attention.size > 0 : !child.settled) settled = false;
+      if (child.thread.isHidden ? child.needsYou.size > 0 : !child.quietIgnoringOpen) quietIgnoringOpen = false;
       if (!child.thread.isHidden) visibleCount += 1;
       visibleCount += below.visibleCount;
-      if (!below.settled) settled = false;
+      if (!below.quietIgnoringOpen) quietIgnoringOpen = false;
     }
     path.delete(id);
-    const subtree: Subtree = { descendants, flags, visibleCount, settled };
+    const subtree: Subtree = { descendants, flags, visibleCount, quietIgnoringOpen };
     subtrees.set(id, subtree);
     return subtree;
   };
@@ -236,27 +236,29 @@ export function buildForest(inputs: ForestInputs): Forest {
   const familyOf = new Map<string, Family>();
   for (const root of roots) {
     const { descendants, flags: descendantFlags, visibleCount: visibleDescendantCount } = subtrees.get(root.thread.id)!;
-    let attention = root.thread.latestAttentionAt;
+    let latestAttentionAt = root.thread.latestAttentionAt;
     let quiet = root.quiet;
-    let settled = isQuietThread(root.state, root.unread, false);
+    let quietIgnoringOpen = isQuietThread(root.state, root.unread, false);
     let containsActive = root.isActive;
-    const attentionFlags = new Set<Flag>();
+    const needsYouFlags = new Set<Flag>();
     for (const info of descendants) {
-      if (!info.thread.isArchived) for (const flag of info.attention) attentionFlags.add(flag);
-      attention = Math.max(attention, info.thread.latestAttentionAt);
+      if (!info.thread.isArchived) for (const flag of info.needsYou) needsYouFlags.add(flag);
+      latestAttentionAt = Math.max(latestAttentionAt, info.thread.latestAttentionAt);
       if (info.isActive) containsActive = true;
       if (info.thread.isHidden) {
-        if (info.attention.size > 0) quiet = settled = false;
+        if (info.needsYou.size > 0) quiet = quietIgnoringOpen = false;
       } else {
         if (!info.quiet) quiet = false;
-        if (!isQuietThread(info.state, info.unread, false)) settled = false;
+        // A child reads as its own fold does, so with `blocked` an unread child
+        // does not keep an old family out of the group's fold.
+        if (!info.quietIgnoringOpen) quietIgnoringOpen = false;
       }
     }
     const flags = new Set<Flag>(descendantFlags);
     if (!root.thread.isArchived) {
-      for (const flag of root.attention) {
+      for (const flag of root.needsYou) {
         flags.add(flag);
-        attentionFlags.add(flag);
+        needsYouFlags.add(flag);
       }
       if (root.flags.has("working")) flags.add("working");
     }
@@ -265,11 +267,11 @@ export function buildForest(inputs: ForestInputs): Forest {
       descendants,
       descendantFlags,
       flags,
-      attentionFlags,
+      needsYouFlags,
       visibleDescendantCount,
-      attention,
+      latestAttentionAt,
       quiet: quiet && !containsActive,
-      settled,
+      quietIgnoringOpen,
       containsActive,
     };
     families.push(family);

package/features/thread-list/model/labels.ts

@@ -12,7 +12,7 @@ export function stateText(row: ThreadRow, pluginLabel: string | null): string {
   return base;
 }
 
-/** "Open Fix login — Working; Claude Code; child of Manager; unread". */
+/** "Open Fix login — Working; Claude Code; child of Release; unread". */
 export function rowAriaLabel(
   row: ThreadRow,
   options: { providerName: string; pluginLabel: string | null; hasDraft: boolean },
@@ -20,6 +20,7 @@ export function rowAriaLabel(
   const parts = [stateText(row, options.pluginLabel), options.providerName];
   if (row.parentTitle !== null && row.depth > 0) parts.push(`child of ${row.parentTitle}`);
   if (row.crossGroupLabel !== null) parts.push(row.crossGroupLabel.toLowerCase());
+  if (row.homeGroupLabel !== null) parts.push(`in ${row.homeGroupLabel}`);
   if (row.hiddenBadge) parts.push("hidden thread");
   if (row.info.unread && row.info.state.kind !== "unread") parts.push("unread");
   if (options.hasDraft && row.info.state.kind !== "draft") parts.push("unsubmitted draft");

package/features/thread-list/model/layout.ts

@@ -1,25 +1,20 @@
 // How far a row sits from the list's left edge. Pure, so a test can
 // call it without rendering.
-import type { Nesting } from "@/shared/preferences";
-
 /** Left padding of a root row, as in bb's list. */
 export const ROOT_INDENT = 8;
-/** Tree nesting keeps bb's step per level. */
-export const TREE_STEP = 24;
 /**
- * Folded nesting shows one flat level. A child's status slot starts this far
- * right of its parent's, so the child's title sits this far right of the
- * parent's title.
+ * A child's status slot starts this far right of its parent's, so the
+ * child's title sits this far right of the parent's title.
  */
 export const FOLDED_STEP = 12;
 
-export function rowIndent(depth: number, nesting: Nesting): number {
-  return ROOT_INDENT + depth * (nesting === "tree" ? TREE_STEP : FOLDED_STEP);
+export function rowIndent(depth: number): number {
+  return ROOT_INDENT + depth * FOLDED_STEP;
 }
 
 /** How far the rail sits from a row's left edge: the centre of the status slot at that level. */
-export function railLeft(level: number, nesting: Nesting): number {
-  return rowIndent(level, nesting) + 8;
+export function railLeft(level: number): number {
+  return rowIndent(level) + 8;
 }
 
 /**

package/features/thread-list/model/needs-you.ts

@@ -0,0 +1,133 @@
+// What needs you, thread by thread. The Needs you section, the header
+// counters, the section's order and auto-reveal all read the set this
+// builds. Pure.
+import type { PluginSidebarThread } from "@get-bb/plugin-sdk/app";
+import type { ChildAttention } from "@/shared/preferences";
+import type { Family } from "./families";
+import { type Flag, type StateKind, type ThreadState } from "./state";
+
+/** The flags that count for a root thread. Working is not one. */
+export const ROOT_NEEDS_YOU: ReadonlySet<Flag> = new Set<Flag>([
+  "waits-on-you",
+  "unread-failed",
+  "queue-failed",
+  "offline",
+  "unread",
+]);
+
+/** States in which a parent thread is busy and may still deal with a failed child. */
+const BUSY: ReadonlySet<StateKind> = new Set<StateKind>(["working", "background", "queued", "scheduled"]);
+
+export interface ParentThread {
+  thread: Pick<PluginSidebarThread, "latestAttentionAt">;
+  state: Pick<ThreadState, "kind">;
+  /** When the plugin server last saw the parent thread finish a turn, if it did. */
+  finishedAt?: number;
+}
+
+/** A parent thread is idle when it is not working, setting up, running background work or holding a queued message. */
+export function isParentIdle(parent: ParentThread): boolean {
+  return !BUSY.has(parent.state.kind);
+}
+
+/** When the thread's failure happened: an error bumps `latestAttentionAt`, a failed queue only `updatedAt`. */
+export function failureTime(
+  thread: Pick<PluginSidebarThread, "latestAttentionAt" | "updatedAt">,
+  flags: ReadonlySet<Flag>,
+): number {
+  let at = 0;
+  if (flags.has("unread-failed")) at = Math.max(at, thread.latestAttentionAt);
+  if (flags.has("queue-failed")) at = Math.max(at, thread.updatedAt);
+  return at;
+}
+
+/**
+ * An orphaned failure: the parent thread is idle and has not run or
+ * finished since the child failed. A busy parent thread, or one that
+ * finished after the failure, is taken to know about it. The parent thread's
+ * own clock is its last finish (`finishedAt`, or `latestAttentionAt` when it
+ * failed): `updatedAt` also moves when someone merely opens or renames it.
+ */
+export function isOrphanedFailure(
+  thread: Pick<PluginSidebarThread, "latestAttentionAt" | "updatedAt">,
+  flags: ReadonlySet<Flag>,
+  parent: ParentThread,
+): boolean {
+  if (!flags.has("unread-failed") && !flags.has("queue-failed")) return false;
+  if (!isParentIdle(parent)) return false;
+  const parentActiveAt = Math.max(parent.thread.latestAttentionAt, parent.finishedAt ?? 0);
+  return parentActiveAt <= failureTime(thread, flags);
+}
+
+/**
+ * The flags of one thread that make it need you. A root keeps its own. A
+ * child counts when it waits on you or is offline, or for an orphaned
+ * failure; a finished-unread child never does. With `everything`, a child
+ * counts like a root.
+ */
+export function needsYouFlagsOf(
+  flags: ReadonlySet<Flag>,
+  options: { isRoot: boolean; mode: ChildAttention; orphaned: boolean },
+): Set<Flag> {
+  const kept = new Set<Flag>();
+  if (options.isRoot || options.mode === "everything") {
+    for (const flag of flags) if (ROOT_NEEDS_YOU.has(flag)) kept.add(flag);
+    return kept;
+  }
+  if (flags.has("waits-on-you")) kept.add("waits-on-you");
+  if (flags.has("offline")) kept.add("offline");
+  if (options.orphaned) {
+    if (flags.has("unread-failed")) kept.add("unread-failed");
+    if (flags.has("queue-failed")) kept.add("queue-failed");
+  }
+  return kept;
+}
+
+/** Whether a set of Needs you flags is worth an auto-reveal: it waits on you or failed. */
+export function revealsOn(needsYou: ReadonlySet<Flag>, isRoot: boolean): boolean {
+  if (needsYou.has("waits-on-you") || needsYou.has("unread-failed")) return true;
+  return !isRoot && needsYou.has("queue-failed");
+}
+
+/** What the section reads of a family. */
+type SectionFamily = Pick<Family, "root" | "needsYouFlags">;
+
+/** What Needs you remembers between renders: the family it holds, and the family that was open. */
+export interface NeedsYouHold {
+  /** The root of the family held in the section, if any. */
+  heldRootId: string | null;
+  /** The root of the family the open thread belonged to at the last render, if any. */
+  openRootId: string | null;
+}
+
+export const NO_HOLD: NeedsYouHold = { heldRootId: null, openRootId: null };
+
+/**
+ * Whether a family is in the Needs you section: it is the held family, or one
+ * of its threads needs you and none of them is open. Nothing moves while you
+ * are inside a family, so the open family only enters by being judged when
+ * opened (see `holdNeedsYou`).
+ */
+export function inNeedsYou(family: SectionFamily, heldRootId: string | null, openRootId: string | null): boolean {
+  const rootId = family.root.thread.id;
+  if (rootId === heldRootId) return true;
+  return family.needsYouFlags.size > 0 && rootId !== openRootId;
+}
+
+/**
+ * The hold after a render. A family is judged when a thread in it is opened
+ * from outside it: it is held if something in it needs you then, and it stays
+ * held while one of its threads is open, after nothing in it needs you any
+ * more, until a thread outside it is opened. A family that does not need you
+ * when opened is not pulled in later, whatever happens in it; nor is one
+ * that never needed you. Opening another thread of the open family judges
+ * nothing again.
+ */
+export function holdNeedsYou(previous: NeedsYouHold, openFamily: SectionFamily | undefined): NeedsYouHold {
+  if (openFamily === undefined) return NO_HOLD;
+  const openRootId = openFamily.root.thread.id;
+  if (openRootId === previous.openRootId) {
+    return { heldRootId: previous.heldRootId === openRootId ? openRootId : null, openRootId };
+  }
+  return { heldRootId: openFamily.needsYouFlags.size > 0 ? openRootId : null, openRootId };
+}

package/features/thread-list/model/notes.ts

@@ -18,7 +18,7 @@ const PENDING_PREFIX: Record<NeedsKind, string> = {
   input: "Needs",
 };
 
-/** The needs-you kind a pending note names, or null when there is none. */
+/** What a pending note says the thread waits on you for, or null when there is none. */
 export function needsKindOf(notes: ThreadNotes | undefined): NeedsKind | null {
   const kind = notes?.pending?.kind;
   return kind === "question" || kind === "approval" || kind === "plan" || kind === "input" ? kind : null;

package/features/thread-list/model/settings.ts

@@ -0,0 +1,54 @@
+// What the settings popover's controls show and write. Pure.
+import type { ChildAttention, Lifecycle, Preferences, SortField } from "@/shared/preferences";
+import { effectiveDirection, effectiveSortField, naturalDirection } from "./sort";
+
+export type ThreadsShown = "active" | "archived" | "both";
+
+/** The Threads choice a saved lifecycle list stands for. */
+export function threadsShown(lifecycles: readonly Lifecycle[]): ThreadsShown {
+  const active = lifecycles.includes("active");
+  const archived = lifecycles.includes("archived");
+  if (active && archived) return "both";
+  return archived ? "archived" : "active";
+}
+
+/** The lifecycles a Threads choice saves; never empty. */
+export function lifecyclesFor(shown: ThreadsShown): Lifecycle[] {
+  if (shown === "both") return ["active", "archived"];
+  return [shown];
+}
+
+/** "Needs you counts every child" is on when children count as `everything`. */
+export function countsEveryChild(childAttention: ChildAttention): boolean {
+  return childAttention === "everything";
+}
+
+export function childAttentionFor(everyChild: boolean): ChildAttention {
+  return everyChild ? "everything" : "blocked";
+}
+
+/** Choosing a field starts it in its own direction, as a saved `default` did. */
+export function sortFieldPatch(field: Exclude<SortField, "none">): Partial<Preferences> {
+  return { chronologicalSort: field, sortDirection: naturalDirection(field) };
+}
+
+export interface SortArrow {
+  glyph: "↓" | "↑";
+  /** The order the list is in now, in words. */
+  label: string;
+  /** What pressing the arrow saves. */
+  patch: Partial<Preferences>;
+}
+
+/** The ↓/↑ button: ↓ descending (newest first, Z–A), ↑ ascending. */
+export function sortArrow(prefs: Pick<Preferences, "chronologicalSort" | "sortDirection">): SortArrow {
+  const field = effectiveSortField(prefs.chronologicalSort);
+  const direction = effectiveDirection(field, prefs.sortDirection);
+  const descending = direction === "descending";
+  const label = field === "alpha" ? (descending ? "Z–A" : "A–Z") : descending ? "Newest first" : "Oldest first";
+  return {
+    glyph: descending ? "↓" : "↑",
+    label,
+    patch: { sortDirection: descending ? "ascending" : "descending" },
+  };
+}

package/features/thread-list/model/share.ts

@@ -1,6 +1,6 @@
 // Structural sharing between two list views: whatever did not change keeps
 // the previous object, so memoized rows and groups skip their render. Pure.
-import type { GroupView, ListView, Row } from "./view";
+import type { GroupView, ListView, NeedsYouView, Row } from "./view";
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   if (value === null || typeof value !== "object") return false;
@@ -86,6 +86,11 @@ function shareGroups(previousGroups: GroupView[], all: ReadonlyMap<string, Group
   return sameItems(previousGroups, result) ? previousGroups : result;
 }
 
+function shareNeedsYou(previous: NeedsYouView | null, next: NeedsYouView | null): NeedsYouView | null {
+  if (previous === null || next === null) return next;
+  return shareFields(previous, next, { rows: shareRows(previous.rows, next.rows) });
+}
+
 /**
  * `next`, sharing every group and row that did not change since `previous`.
  * Groups match by id and rows by key, never by position. A group keeps its
@@ -95,6 +100,7 @@ export function shareView(previous: ListView | null, next: ListView): ListView {
   if (previous === null) return next;
   const all = new Map([...previous.groups, ...previous.more].map((group) => [group.descriptor.id, group]));
   return shareFields(previous, next, {
+    needsYou: shareNeedsYou(previous.needsYou, next.needsYou),
     groups: shareGroups(previous.groups, all, next.groups),
     more: shareGroups(previous.more, all, next.more),
   });

package/features/thread-list/model/sort.ts

@@ -38,15 +38,23 @@ export function effectiveSortField(field: SortField): Exclude<SortField, "none">
   return field === "none" ? "updated" : field;
 }
 
+/** A field's own direction: A–Z for names, newest first for dates. */
+export function naturalDirection(field: SortField): "ascending" | "descending" {
+  return effectiveSortField(field) === "alpha" ? "ascending" : "descending";
+}
+
+/** The direction the list is sorted in: a saved `default` reads as the field's own. */
+export function effectiveDirection(field: SortField, direction: SortDirection): "ascending" | "descending" {
+  return direction === "default" ? naturalDirection(field) : direction;
+}
+
 /**
- * The comparator for roots in a group. Direction follows bb: `default` keeps
- * the field's natural direction (ascending for alpha, descending otherwise).
- * Working first keeps active threads on top whatever the direction.
+ * The comparator for roots in a group. Working first keeps active threads on
+ * top whatever the direction.
  */
 export function makeComparator(options: SortOptions): (a: SortKey, b: SortKey) => number {
   const field = effectiveSortField(options.field);
-  const natural = field === "alpha" ? "ascending" : "descending";
-  const sign = options.direction === "default" || options.direction === natural ? 1 : -1;
+  const sign = effectiveDirection(field, options.direction) === naturalDirection(field) ? 1 : -1;
   const base = field === "alpha" ? byAlpha : field === "created" ? byCreated : byUpdated;
   return (a, b) => {
     if (field === "updated" && options.workingFirst) {
@@ -70,7 +78,7 @@ export function comparePinned(a: PluginSidebarThread, b: PluginSidebarThread): n
   return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
 }
 
-/** Children in Folded nesting: creation order. */
+/** Children under a chip: creation order. */
 export function compareCreationAscending(a: PluginSidebarThread, b: PluginSidebarThread): number {
   const diff = a.createdAt - b.createdAt;
   if (diff !== 0) return diff;

package/features/thread-list/model/state.ts

@@ -6,7 +6,7 @@ import type {
 } from "@get-bb/plugin-sdk/app";
 
 export type StateKind =
-  | "needs-you"
+  | "waits-on-you"
   | "failed"
   | "queue-failed"
   | "offline"
@@ -19,11 +19,11 @@ export type StateKind =
   | "idle";
 
 /** A rollup flag. Set independently of the first-match state. */
-export type Flag = "needs-you" | "unread-failed" | "queue-failed" | "offline" | "working" | "unread";
+export type Flag = "waits-on-you" | "unread-failed" | "queue-failed" | "offline" | "working" | "unread";
 
 /** Flags, most urgent first. */
 export const FLAG_ORDER: readonly Flag[] = [
-  "needs-you",
+  "waits-on-you",
   "unread-failed",
   "queue-failed",
   "offline",
@@ -179,7 +179,7 @@ export function computeState(thread: PluginSidebarThread, inputs: StateInputs):
   if (thread.hasPendingInteraction) {
     const needs = NEEDS[inputs.needsKind ?? "input"] ?? NEEDS.input;
     const icon = inputs.needsKind ? needs.icon : "CircleQuestion";
-    return { kind: "needs-you", label: needs.label, glyph: glyph(icon, "attention"), ...none };
+    return { kind: "waits-on-you", label: needs.label, glyph: glyph(icon, "attention"), ...none };
   }
   if (status === "error") {
     return {
@@ -236,14 +236,14 @@ export function computeState(thread: PluginSidebarThread, inputs: StateInputs):
 
 /**
  * A plugin row status replaces the glyph for every state except
- * needs-you, failed, and working with its plain spinner (the rule bb's list uses).
+ * waits-on-you, failed, and working with its plain spinner (the rule bb's list uses).
  */
 export function pluginStatusWins(
   state: ThreadState,
   rowStatus: PluginSidebarThreadRowStatus | null,
 ): boolean {
   if (rowStatus === null) return false;
-  if (state.kind === "needs-you" || state.kind === "failed") return false;
+  if (state.kind === "waits-on-you" || state.kind === "failed") return false;
   if (state.kind === "working" && state.glyph.spin) return false;
   return true;
 }
@@ -251,7 +251,7 @@ export function pluginStatusWins(
 /** The rollup flags a single thread carries. */
 export function threadFlags(thread: PluginSidebarThread, unread: boolean): Set<Flag> {
   const flags = new Set<Flag>();
-  if (thread.hasPendingInteraction) flags.add("needs-you");
+  if (thread.hasPendingInteraction) flags.add("waits-on-you");
   if (normalizeStatus(thread) === "error" && unread) flags.add("unread-failed");
   if (normalizeQueued(thread) === "failed") flags.add("queue-failed");
   if (isOffline(thread)) flags.add("offline");
@@ -260,10 +260,10 @@ export function threadFlags(thread: PluginSidebarThread, unread: boolean): Set<F
   return flags;
 }
 
-/** Flags hidden threads contribute: needs-you and unread-failed only. */
+/** Flags hidden threads contribute: waits-on-you and unread-failed only. */
 export function hiddenThreadFlags(flags: ReadonlySet<Flag>): Set<Flag> {
   const kept = new Set<Flag>();
-  if (flags.has("needs-you")) kept.add("needs-you");
+  if (flags.has("waits-on-you")) kept.add("waits-on-you");
   if (flags.has("unread-failed")) kept.add("unread-failed");
   return kept;
 }
@@ -279,7 +279,7 @@ export type ChipTone = "attention" | "destructive" | "working" | "neutral";
 /** The tone of a chip whose most urgent rolled-up flag is `flag`. */
 export function chipTone(flag: Flag | null): ChipTone {
   switch (flag) {
-    case "needs-you":
+    case "waits-on-you":
       return "attention";
     case "unread-failed":
     case "queue-failed":
@@ -292,7 +292,7 @@ export function chipTone(flag: Flag | null): ChipTone {
 }
 
 export const FLAG_GLYPHS: Readonly<Record<Flag, Glyph & { label: string }>> = {
-  "needs-you": { ...glyph("CircleQuestion", "attention"), label: "needs your input" },
+  "waits-on-you": { ...glyph("CircleQuestion", "attention"), label: "needs your input" },
   "unread-failed": { ...glyph("CircleX", "destructive"), label: "failed" },
   "queue-failed": { ...glyph("AlertTriangle", "destructive"), label: "queued message failed" },
   offline: { ...glyph("CloudOff", "attention"), label: "machine offline" },

package/features/thread-list/model/time.ts

@@ -97,7 +97,7 @@ export function stateSince(
   const at =
     kind === "working"
       ? stamps.startedAt[threadId]
-      : kind === "needs-you"
+      : kind === "waits-on-you"
         ? stamps.pendingAt[threadId]
         : kind === "idle" || kind === "unread" || kind === "failed"
           ? stamps.finishedAt[threadId]