@tangle-network/ui 11.47.0 → 11.49.0

package/dist/run.js

@@ -1,3 +1,4 @@
+import { RunStatusIcon, runStatus, statusMeta } from "./run/status-meta.js";
 import { ExpandedToolDetail } from "./run/expanded-tool-detail.js";
 import { RunRowShell, RunRowStatusDot } from "./run/run-row-shell.js";
 import { InlineToolItem } from "./run/inline-tool-item.js";
@@ -8,4 +9,4 @@ import { ToolCallFeed, parseToolEvent } from "./run/tool-call-feed.js";
 import { TaskList, showsTaskPriority, taskProgress, taskStatus } from "./run/task-list.js";
 import { ApprovalCard, ApprovalDiffSummary } from "./run/approval-card.js";
 import { RunPhaseList } from "./run/run-phase-list.js";
-export { ApprovalCard, ApprovalDiffSummary, ExpandedToolDetail, InlineThinkingItem, InlineToolItem, LiveDuration, RunGroup, RunPhaseList, RunRowShell, RunRowStatusDot, TaskList, ToolCallFeed, parseToolEvent, showsTaskPriority, taskProgress, taskStatus };
+export { ApprovalCard, ApprovalDiffSummary, ExpandedToolDetail, InlineThinkingItem, InlineToolItem, LiveDuration, RunGroup, RunPhaseList, RunRowShell, RunRowStatusDot, RunStatusIcon, TaskList, ToolCallFeed, parseToolEvent, runStatus, showsTaskPriority, statusMeta, taskProgress, taskStatus };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/ui",
-  "version": "11.47.0",
+  "version": "11.49.0",
   "description": "Generic React UI components for Tangle products — primitives, chat, run, files, editor, markdown.",
   "type": "module",
   "license": "MIT",
@@ -166,7 +166,7 @@
   "peerDependencies": {
     "@hocuspocus/provider": ">=2.15.0 <5.0.0",
     "@nanostores/react": ">=0.8.4 <3.0.0",
-    "@tangle-network/brand": "^1.29.0",
+    "@tangle-network/brand": "^1.30.0",
     "@tiptap/core": ">=3.20.4 <4.0.0",
     "@tiptap/extension-collaboration": ">=3.20.4 <4.0.0",
     "@tiptap/extension-collaboration-caret": ">=3.7.0 <4.0.0",

package/src/chat/index.ts

@@ -3,6 +3,15 @@ export { MessageList, type MessageListProps } from "./message-list";
 export { UserMessage, type UserMessageProps } from "./user-message";
 export { ChatMessage, type ChatMessageProps, type MessageRole } from "./chat-message";
 export { MessageAuthor, isViewerMessage, type MessageAuthorProps } from "./message-author";
+export {
+  SpeakerHeader,
+  partitionBySpeaker,
+  type Speaker,
+  type SpeakerHeaderProps,
+  type SpeakerPart,
+  type SpeakerSection,
+  type SpeakerState,
+} from "./speaker";
 export type { ChatAuthor } from "../types/message";
 export { ThinkingIndicator, type ThinkingIndicatorProps } from "./thinking-indicator";
 export {

package/src/chat/message-author.tsx

@@ -15,20 +15,21 @@ export function isViewerMessage(author: ChatAuthor | undefined, viewerId: string
   return author === undefined || author.id === viewerId;
 }
 
-export interface MessageAuthorProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+export interface MessageAuthorProps extends HTMLAttributes<HTMLDivElement> {
   author: ChatAuthor;
 }
 
 /**
  * The line above a message in a transcript with several participants: the
- * author's avatar, name and, when given, their role as a tag.
+ * author's avatar, name and, when given, their role as a tag. Children follow
+ * on the same line, such as a responder's handle and state.
  *
  * The avatar's tone comes from the author's id, so a participant keeps one
  * colour for the whole thread and in every product. Tones can repeat between
  * participants, so the name is always shown beside it. The avatar repeats the
  * visible name and is hidden from assistive technology.
  */
-export function MessageAuthor({ author, className, ...props }: MessageAuthorProps) {
+export function MessageAuthor({ author, className, children, ...props }: MessageAuthorProps) {
   return (
     <div data-message-author="" className={cn("flex min-w-0 max-w-full items-center gap-2", className)} {...props}>
       <IconTile
@@ -47,6 +48,7 @@ export function MessageAuthor({ author, className, ...props }: MessageAuthorProp
           {author.role}
         </Tag>
       ) : null}
+      {children}
     </div>
   );
 }

package/src/chat/speaker.stories.tsx

@@ -0,0 +1,95 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { partitionBySpeaker, SpeakerHeader } from './speaker'
+import { TRANSCRIPT_TEXT } from './transcript-text'
+
+type Part =
+  | { type: 'speaker'; id: string; name: string; handle?: string; state?: 'answering' | 'done' | 'failed' }
+  | { type: 'text'; text: string; speaker?: string }
+  | { type: 'tool'; tool: string; status: string; speaker?: string }
+  | { type: 'notice'; text: string; speaker?: string }
+
+/** One turn's parts drawn the way a product draws them: a header per responder, its parts under it. */
+function Turn({ parts, live = false }: { parts: Part[]; live?: boolean }) {
+  return (
+    <div className="mx-auto flex w-full max-w-3xl flex-col gap-6 px-4 py-6">
+      <p className={`ml-auto w-fit max-w-[78%] rounded-2xl bg-foreground px-4 py-3 text-background ${TRANSCRIPT_TEXT}`}>
+        @writer @research-lead plan the launch announcement for the roster feature.
+      </p>
+      {partitionBySpeaker(parts).map(({ speaker, parts: own }) => (
+        <section key={speaker?.id ?? 'turn'} className="flex flex-col gap-2">
+          {speaker ? <SpeakerHeader speaker={speaker} live={live} /> : null}
+          {own.map((part, index) =>
+            part.type === 'text' ? (
+              <p key={index} className={TRANSCRIPT_TEXT}>{part.text}</p>
+            ) : part.type === 'tool' ? (
+              <p key={index} className="font-mono text-muted-foreground text-sm">{part.tool} · {part.status}</p>
+            ) : part.type === 'notice' ? (
+              <p key={index} className="text-[var(--surface-danger-text)] text-sm">{part.text}</p>
+            ) : null,
+          )}
+        </section>
+      ))}
+    </div>
+  )
+}
+
+const meta: Meta<typeof Turn> = {
+  title: 'Chat/Speakers',
+  component: Turn,
+  parameters: { layout: 'fullscreen' },
+  decorators: [
+    (Story) => (
+      <div className="min-h-screen bg-[var(--bg-root)]">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof Turn>
+
+/**
+ * A live turn as the stream delivers it: both responders announced first, then
+ * their output interleaved, each part tagged with its responder. The Writer has
+ * reported its end; the Research Lead is still answering.
+ */
+export const AnsweringAtOnce: Story = {
+  args: {
+    live: true,
+    parts: [
+      { type: 'speaker', id: 'ap_writer', name: 'Writer', handle: 'writer' },
+      { type: 'speaker', id: 'ap_research', name: 'Research Lead', handle: 'research-lead' },
+      { type: 'text', speaker: 'ap_writer', text: 'Draft headline: "Every agent in your workspace, one @ away."' },
+      { type: 'tool', speaker: 'ap_research', tool: 'search_repo', status: 'running' },
+      { type: 'text', speaker: 'ap_writer', text: 'Subhead: address any agent from any thread, and let it run on a schedule while you sleep.' },
+      { type: 'speaker', id: 'ap_writer', name: 'Writer', handle: 'writer', state: 'done' },
+      { type: 'text', speaker: 'ap_research', text: 'Checking the roster and the mention routes before naming risks.' },
+    ],
+  },
+}
+
+/** A stored row: a speaker part before each answer. The Research Lead failed and keeps its header and its notice. */
+export const StoredWithFailure: Story = {
+  args: {
+    parts: [
+      { type: 'speaker', id: 'ap_writer', name: 'Writer', handle: 'writer', state: 'done' },
+      { type: 'text', text: 'Draft headline: "Every agent in your workspace, one @ away."' },
+      { type: 'speaker', id: 'ap_research', name: 'Research Lead', handle: 'research-lead', state: 'failed' },
+      { type: 'tool', tool: 'search_repo', status: 'error' },
+      { type: 'notice', text: 'Research Lead could not answer: the model provider refused the request (429).' },
+    ],
+  },
+}
+
+/** Worst case for a phone: a long name and handle while answering. The name and handle truncate; the state stays whole. */
+export const LongNames: Story = {
+  args: {
+    live: true,
+    parts: [
+      { type: 'speaker', id: 'ap_compliance', name: 'Regional Compliance and Disclosure Reviewer', handle: 'regional-compliance-disclosure-reviewer' },
+      { type: 'text', text: 'Reading the disclosure rules for each launch region.' },
+      { type: 'speaker', id: 'ap_q', name: 'Q', state: 'failed' },
+    ],
+  },
+}

package/src/chat/speaker.test.tsx

@@ -0,0 +1,81 @@
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import { MessageAuthor } from "./message-author"
+import { partitionBySpeaker, SpeakerHeader, type Speaker } from "./speaker"
+
+type Part = { type: string; id?: string; name?: string; handle?: string; state?: Speaker["state"]; text?: string; speaker?: string }
+
+const writer = { type: "speaker", id: "ap_writer", name: "Writer", handle: "writer" }
+const research = { type: "speaker", id: "ap_research", name: "Research Lead", handle: "research-lead" }
+const text = (value: string, speaker?: string): Part => ({ type: "text", text: value, ...(speaker ? { speaker } : {}) })
+
+/** Each section as `[speaker id or null, its texts]`. */
+const shape = (parts: Part[]) =>
+  partitionBySpeaker(parts).map((section) => [section.speaker?.id ?? null, section.parts.map((part) => part.text)])
+
+describe("partitionBySpeaker", () => {
+  it("splits a stored row at its speaker parts, in stored order", () => {
+    expect(shape([writer, text("headline"), text("subhead"), research, text("risks")])).toEqual([
+      ["ap_writer", ["headline", "subhead"]],
+      ["ap_research", ["risks"]],
+    ])
+  })
+
+  it("groups a live stream by each part's speaker tag, not by where it arrived", () => {
+    const live = [writer, research, text("headline", "ap_writer"), text("searching", "ap_research"), text("subhead", "ap_writer"), text("risks", "ap_research")]
+    expect(shape(live)).toEqual([
+      ["ap_writer", ["headline", "subhead"]],
+      ["ap_research", ["searching", "risks"]],
+    ])
+  })
+
+  it("takes a responder's end state from a later speaker part, without a second section", () => {
+    const sections = partitionBySpeaker<Part>([writer, research, text("headline", "ap_writer"), { ...writer, state: "done" }, text("risks", "ap_research")])
+    expect(sections.map((section) => [section.speaker?.name, section.speaker?.state])).toEqual([["Writer", "done"], ["Research Lead", undefined]])
+    expect(sections[1]?.parts.map((part) => part.text)).toEqual(["risks"])
+  })
+
+  it("keeps parts no speaker owns, first, and drops none", () => {
+    expect(shape([text("preamble"), writer, text("headline"), text("stray", "ap_nobody")])).toEqual([
+      [null, ["preamble", "stray"]],
+      ["ap_writer", ["headline"]],
+    ])
+    expect(shape([text("one agent"), text("one answer")])).toEqual([[null, ["one agent", "one answer"]]])
+    expect(shape([])).toEqual([[null, []]])
+  })
+})
+
+describe("SpeakerHeader", () => {
+  it("names the responder in its own element, with its handle, answering while the turn runs", () => {
+    const { container } = render(<SpeakerHeader speaker={{ id: "ap_writer", name: "Writer", handle: "writer" }} live />)
+    expect(screen.getByText(/^Writer$/)).toBeInTheDocument()
+    expect(screen.getByText("@writer")).toBeInTheDocument()
+    expect(screen.getByText("Answering")).toBeInTheDocument()
+    expect(container.querySelector("[data-speaker-state]")?.getAttribute("data-speaker-state")).toBe("answering")
+  })
+
+  it("says nothing more once the responder has ended, even while others answer", () => {
+    const { container } = render(<SpeakerHeader speaker={{ id: "ap_writer", name: "Writer", state: "done" }} live />)
+    expect(screen.queryByText("Answering")).not.toBeInTheDocument()
+    expect(screen.queryByText("Failed")).not.toBeInTheDocument()
+    expect(container.querySelector("[data-speaker-state]")?.getAttribute("data-speaker-state")).toBe("done")
+  })
+
+  it("shows a failed responder as failed while the turn still runs", () => {
+    render(<SpeakerHeader speaker={{ id: "ap_research", name: "Research Lead", state: "failed" }} live />)
+    expect(screen.getByText("Failed")).toBeInTheDocument()
+    expect(screen.queryByText("Answering")).not.toBeInTheDocument()
+  })
+
+  it("treats a responder without an end state on a finished turn as done", () => {
+    const { container } = render(<SpeakerHeader speaker={{ id: "ap_writer", name: "Writer" }} />)
+    expect(container.querySelector("[data-speaker-state]")?.getAttribute("data-speaker-state")).toBe("done")
+  })
+
+  it("draws the author line every participant gets, so an agent keeps its tone", () => {
+    const avatar = (node: HTMLElement) => node.querySelector("[aria-hidden]")!.className
+    const header = render(<SpeakerHeader speaker={{ id: "ap_writer", name: "Writer" }} />).container
+    const author = render(<MessageAuthor author={{ id: "ap_writer", name: "Writer" }} />).container
+    expect(avatar(header)).toBe(avatar(author))
+  })
+})

package/src/chat/speaker.tsx

@@ -0,0 +1,110 @@
+import type { HTMLAttributes } from "react";
+import { StatusPill } from "../primitives/status-pill";
+import { MessageAuthor } from "./message-author";
+
+/** Where one responder is in its answer. */
+export type SpeakerState = "answering" | "done" | "failed";
+
+/**
+ * A responder of a turn addressed to several agents. In the turn's parts it is
+ * a `{ type: "speaker", id, name, handle?, state? }` part written before the
+ * responder's answer.
+ */
+export interface Speaker {
+  /** The agent's stable id. It keys the avatar's tone and a live part's `speaker` tag. */
+  id: string;
+  name: string;
+  /** What a person types after `@` to address the agent. */
+  handle?: string;
+  /** Set once the responder ended; absent while it answers and on rows written before responders reported an end. */
+  state?: SpeakerState;
+}
+
+export type SpeakerPart = Speaker & { type: "speaker" };
+
+/** One responder's share of a turn: its speaker part and the parts it wrote. */
+export interface SpeakerSection<T> {
+  /** The latest speaker part for this responder; null for the parts no speaker owns. */
+  speaker: (T & SpeakerPart) | null;
+  parts: T[];
+}
+
+function isSpeakerPart<T>(part: T): part is T & SpeakerPart {
+  const record = part as { type?: unknown; id?: unknown; name?: unknown } | null;
+  return !!record && record.type === "speaker" && typeof record.id === "string" && typeof record.name === "string";
+}
+
+/**
+ * Splits one assistant turn's parts by the agent that wrote them.
+ *
+ * A stored row holds a speaker part before each responder's answer, so a part
+ * belongs to the speaker part before it. A live stream announces every
+ * responder first and then interleaves their output, so a part names its owner
+ * in `speaker` (the responder's id), which wins over position. A later speaker
+ * part with an id already seen replaces that responder's speaker part, which is
+ * how its end state arrives, and never opens a second section.
+ *
+ * Sections keep the order speakers were first announced. Parts no speaker owns
+ * come first, in a section whose `speaker` is null; a turn without speaker
+ * parts is that one section. No part is dropped, copied or reordered within its
+ * section.
+ */
+export function partitionBySpeaker<T extends object>(parts: readonly T[]): SpeakerSection<T>[] {
+  const sections = new Map<string, SpeakerSection<T>>();
+  const unowned: T[] = [];
+  let current: SpeakerSection<T> | undefined;
+  for (const part of parts) {
+    if (isSpeakerPart(part)) {
+      current = sections.get(part.id);
+      if (current) current.speaker = part;
+      else sections.set(part.id, (current = { speaker: part, parts: [] }));
+      continue;
+    }
+    const tag = (part as { speaker?: unknown }).speaker;
+    const owner = typeof tag === "string" ? sections.get(tag) : current;
+    (owner?.parts ?? unowned).push(part);
+  }
+  const owned = [...sections.values()];
+  return unowned.length > 0 || owned.length === 0 ? [{ speaker: null, parts: unowned }, ...owned] : owned;
+}
+
+export interface SpeakerHeaderProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+  speaker: Speaker;
+  /** The turn is still running, so a responder that has not reported an end is answering. */
+  live?: boolean;
+}
+
+/**
+ * The line above one responder's answer: the author line every participant
+ * gets, then the handle a person types to address the agent, then its state.
+ *
+ * The state comes from the speaker's own end state, else from `live`. An
+ * answering responder shows the status grammar's open ring with the word, a
+ * failed one its cross with the word, and a finished one nothing, as a settled
+ * run row does. `data-speaker-state` carries all three.
+ */
+export function SpeakerHeader({ speaker, live = false, ...props }: SpeakerHeaderProps) {
+  const state: SpeakerState = speaker.state ?? (live ? "answering" : "done");
+  return (
+    <MessageAuthor
+      author={{ id: speaker.id, name: speaker.name }}
+      data-speaker-state={state}
+      {...props}
+    >
+      {speaker.handle ? (
+        <span className="min-w-0 truncate text-muted-foreground text-sm" title={`@${speaker.handle}`}>
+          @{speaker.handle}
+        </span>
+      ) : null}
+      {state === "answering" ? (
+        <StatusPill tone="running" bare size="md" className="shrink-0 py-0">
+          Answering
+        </StatusPill>
+      ) : state === "failed" ? (
+        <StatusPill tone="danger" bare size="md" className="shrink-0 py-0">
+          Failed
+        </StatusPill>
+      ) : null}
+    </MessageAuthor>
+  );
+}

package/src/run/expanded-tool-detail.tsx

@@ -1,11 +1,5 @@
 import { memo } from "react";
-import {
-  ArrowRight,
-  ArrowLeft,
-  AlertCircle,
-  Loader2,
-  FileText,
-} from "lucide-react";
+import { ArrowRight, ArrowLeft, FileText } from "lucide-react";
 import type { ToolPart } from "../types/parts";
 import { getToolDisplayMetadata } from "../utils/tool-display";
 import { CommandPreview } from "../tool-previews/command-preview";
@@ -16,8 +10,8 @@ import { GlobResultsPreview } from "../tool-previews/glob-results-preview";
 import { WebSearchPreview } from "../tool-previews/web-search-preview";
 import { QuestionPreview } from "../tool-previews/question-preview";
 import { DiffPreview } from "../tool-previews/diff-preview";
-import { cn } from "../lib/utils";
 import { ExpandableContent } from "./expandable-content";
+import { RunStatusIcon } from "./status-meta";
 
 export interface ExpandedToolDetailProps {
   part: ToolPart;
@@ -169,7 +163,7 @@ export const ExpandedToolDetail = memo(({ part }: ExpandedToolDetailProps) => {
       {error && (
         <div className="overflow-hidden rounded-[var(--radius-lg)] border border-[var(--surface-danger-border)]">
           <div className="flex items-center gap-2 border-b border-[var(--surface-danger-border)] bg-[var(--surface-danger-bg)] px-3 py-2">
-            <AlertCircle className="h-3 w-3 text-[var(--surface-danger-text)]" />
+            <RunStatusIcon status="failed" aria-hidden className="size-3" />
             <span className="text-xs font-medium uppercase tracking-[0.08em] text-[var(--surface-danger-text)]">
               Error
             </span>
@@ -185,7 +179,7 @@ export const ExpandedToolDetail = memo(({ part }: ExpandedToolDetailProps) => {
       {/* Running state */}
       {(status === "pending" || status === "running") && (
         <div className="flex items-center gap-2 rounded-[var(--radius-md)] border border-border bg-muted px-3 py-3 text-xs text-muted-foreground">
-          <Loader2 className={cn("h-3 w-3 animate-spin text-primary")} />
+          <RunStatusIcon status="running" aria-hidden className="size-3" />
           Running…
         </div>
       )}

package/src/run/index.ts

@@ -37,3 +37,11 @@ export {
   type ApprovalPlanStep,
 } from "./approval-card";
 export { RunPhaseList, type RunPhase } from "./run-phase-list";
+export {
+  RunStatusIcon,
+  runStatus,
+  statusMeta,
+  type RunStatus,
+  type RunStatusIconProps,
+  type StatusMeta,
+} from "./status-meta";

package/src/run/run-group.tsx

@@ -2,7 +2,6 @@ import { memo, useMemo, type ComponentType, type ReactNode } from "react";
 import * as Collapsible from "@radix-ui/react-collapsible";
 import {
   Bot,
-  Loader2,
   ChevronDown,
   ChevronRight,
   Terminal,
@@ -13,7 +12,6 @@ import {
   Globe,
   ClipboardList,
   Settings,
-  Sparkles,
   type LucideProps,
 } from "lucide-react";
 import { cn } from "../lib/utils";
@@ -24,6 +22,7 @@ import type { AgentBranding } from "../types/branding";
 import type { CustomToolRenderer } from "../types/tool-display";
 import { InlineToolItem } from "./inline-tool-item";
 import { InlineThinkingItem } from "./inline-thinking-item";
+import { RunStatusIcon, statusMeta } from "./status-meta";
 import { Markdown } from "../markdown/markdown";
 import { SyntheticText } from "../chat/synthetic-text";
 
@@ -98,7 +97,7 @@ function AssistantShell({
         <span>{branding.label}</span>
         {isStreaming ? (
           <span className="inline-flex items-center gap-1.5">
-            <Loader2 className="h-3 w-3 animate-spin" />
+            <RunStatusIcon status="running" aria-hidden className="size-3" />
             Thinking
           </span>
         ) : null}
@@ -418,7 +417,7 @@ export const RunGroup = memo(
                         key={key}
                         className="flex items-center gap-2 rounded-[var(--radius-lg)] border border-[var(--border-subtle)] bg-[var(--md3-surface-container)] px-4 py-3 text-sm text-muted-foreground"
                       >
-                        <Loader2 className="h-4 w-4 animate-spin text-primary" />
+                        <RunStatusIcon status="running" aria-hidden />
                         Building view…
                       </div>
                     );
@@ -484,17 +483,10 @@ export const RunGroup = memo(
                 ) : null}
                 <span className="ml-auto flex shrink-0 items-center gap-1.5">
                   <CategoryBadges categories={stats.toolCategories} />
-                  {isStreaming ? (
-                    <span className="inline-flex items-center gap-1 rounded-full border border-[var(--border-accent)] bg-[var(--accent-surface-soft)] px-2 py-px text-[10px] font-semibold uppercase text-[var(--accent-text)]">
-                      <Loader2 className="h-2.5 w-2.5 animate-spin" />
-                      Running
-                    </span>
-                  ) : (
-                    <span className="inline-flex items-center gap-1 rounded-full border border-border px-2 py-px text-[10px] font-semibold uppercase text-muted-foreground">
-                      <Sparkles className="h-2.5 w-2.5" />
-                      Done
-                    </span>
-                  )}
+                  <span className="inline-flex items-center gap-1 rounded-full border border-border px-2 py-px text-[10px] font-semibold uppercase text-muted-foreground">
+                    <RunStatusIcon status={isStreaming ? "running" : "done"} aria-hidden className="size-3" />
+                    {statusMeta(isStreaming ? "running" : "done").label}
+                  </span>
                 </span>
               </button>
             </Collapsible.Trigger>
@@ -542,7 +534,7 @@ export const RunGroup = memo(
                     } else if (toolPart.state.status === "running") {
                       node = (
                         <div className="flex items-center gap-3 rounded-[var(--radius-lg)] border border-[var(--border-subtle)] bg-[var(--md3-surface-container)] px-4 py-3 text-sm text-muted-foreground">
-                          <Loader2 className="h-4 w-4 animate-spin text-primary" />
+                          <RunStatusIcon status="running" aria-hidden />
                           Building view…
                         </div>
                       );

package/src/run/run-phase-list.stories.tsx

@@ -0,0 +1,19 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { RunPhaseList } from "./run-phase-list";
+
+const meta: Meta<typeof RunPhaseList> = {
+  title: "Run/RunPhaseList",
+  component: RunPhaseList,
+  parameters: { layout: "padded" },
+};
+export default meta;
+
+export const Phases: StoryObj<typeof RunPhaseList> = {
+  args: {
+    phases: [
+      { id: "find", title: "Find the hero source", summary: "Read 12 files · searched 3 times", status: "done", content: <p>12 reads</p> },
+      { id: "patch", title: "Patch the layout", summary: "2 edits", status: "error", content: <p>An edit failed</p> },
+      { id: "prove", title: "Prove it on a phone", summary: "Running the browser", status: "running", content: <p>Chromium at 390</p> },
+    ],
+  },
+};

package/src/run/run-phase-list.test.tsx

@@ -20,6 +20,14 @@ describe("RunPhaseList", () => {
     expect(screen.queryByText("step detail")).toBeNull();
     fireEvent.click(first);
     expect(screen.getByText("step detail")).toBeInTheDocument();
-    expect(screen.getByLabelText("Had an error")).toBeInTheDocument();
+    expect(screen.getByRole("img", { name: "Failed" }).getAttribute("class")).toMatch(/circle-x/);
+  });
+
+  it("marks a running phase with the breathing status glyph, not a spinner", () => {
+    const { container } = render(
+      <RunPhaseList phases={[{ id: "a", title: "Prove it", status: "running", content: null }]} />,
+    );
+    expect(screen.getByRole("img", { name: "Running" }).getAttribute("data-motion")).toBe("essential");
+    expect(container.querySelector(".animate-spin")).toBeNull();
   });
 });

package/src/run/run-phase-list.tsx

@@ -1,7 +1,8 @@
 import { useState, type ReactNode } from "react";
-import { ChevronRight, CircleAlert, Loader2 } from "lucide-react";
+import { ChevronRight } from "lucide-react";
 import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
+import { RunStatusIcon } from "./status-meta";
 
 export interface RunPhase {
   id: string;
@@ -37,8 +38,7 @@ function PhaseRow({ phase }: { phase: RunPhase }) {
           <span className="font-medium text-foreground">{phase.title}</span>
           {phase.summary && <span className="text-muted-foreground"> · {phase.summary}</span>}
         </span>
-        {phase.status === "running" && <Loader2 aria-label="Running" className="mt-1 size-4 shrink-0 animate-spin text-muted-foreground" />}
-        {phase.status === "error" && <CircleAlert aria-label="Had an error" className="mt-1 size-4 shrink-0 text-[var(--surface-danger-text)]" />}
+        {phase.status && phase.status !== "done" && <RunStatusIcon status={phase.status} className="mt-1" />}
       </button>
       {open && <div id={id} className="mb-2 ml-6 mt-1">{phase.content}</div>}
     </li>

package/src/run/status-meta.tsx

@@ -0,0 +1,92 @@
+import {
+  CircleCheck,
+  CircleDashed,
+  CircleDot,
+  CircleQuestionMark,
+  CircleStop,
+  CircleX,
+  Hand,
+  Hourglass,
+  type LucideIcon,
+  type LucideProps,
+} from "lucide-react";
+import { cn } from "../lib/utils";
+
+/** The states an agent or a run reports. Every surface names them with `statusMeta`. */
+export type RunStatus = "running" | "waiting" | "needs-you" | "done" | "failed" | "stopped" | "idle" | "unknown";
+
+export interface StatusMeta {
+  /** The one word for the state. A qualifier such as "Shipped" follows Done; it never replaces it. */
+  label: string;
+  /** The lucide glyph, drawn on the 16px grid at stroke 1.75 (`RunStatusIcon` does both). */
+  icon: LucideIcon;
+  /** The Brand colour token for the glyph and any bare status text: `color: var(<token>)`. */
+  token: `--${string}`;
+}
+
+// Amber is attention, and only Needs you is attention: waiting on a peer, a
+// stop and an idle agent are neutral. Running takes the info ink that
+// StatusPill's running tone and the run-mix in-flight slice already use, not
+// the accent, so a per-user accent can never make Running read as Done or
+// Failed. Failed is always CircleX; the warning triangle is for warnings.
+const META: Record<RunStatus, StatusMeta> = {
+  running: { label: "Running", icon: CircleDot, token: "--surface-info-text" },
+  waiting: { label: "Waiting", icon: Hourglass, token: "--surface-neutral-text" },
+  "needs-you": { label: "Needs you", icon: Hand, token: "--surface-warning-text" },
+  done: { label: "Done", icon: CircleCheck, token: "--surface-success-text" },
+  failed: { label: "Failed", icon: CircleX, token: "--surface-danger-text" },
+  stopped: { label: "Stopped", icon: CircleStop, token: "--surface-neutral-text" },
+  idle: { label: "Idle", icon: CircleDashed, token: "--surface-neutral-text" },
+  unknown: { label: "Unknown", icon: CircleQuestionMark, token: "--surface-neutral-text" },
+};
+
+// The vocabularies ui and its products already speak, so each maps here once.
+const ALIASES: Record<string, RunStatus> = {
+  active: "running", in_progress: "running", "in-progress": "running", streaming: "running",
+  pending: "waiting", queued: "waiting", blocked: "waiting",
+  "attention-needed": "needs-you", needs_you: "needs-you", needs_input: "needs-you", awaiting_input: "needs-you",
+  completed: "done", complete: "done", success: "done", succeeded: "done", shipped: "done",
+  error: "failed", errored: "failed",
+  cancelled: "stopped", canceled: "stopped", aborted: "stopped",
+};
+
+/** Any status string as a `RunStatus`; a value nothing names reads as Unknown, never as a guess. */
+export function runStatus(status: string): RunStatus {
+  const key = status.trim().toLowerCase();
+  if (Object.hasOwn(META, key)) return key as RunStatus;
+  return Object.hasOwn(ALIASES, key) ? ALIASES[key] : "unknown";
+}
+
+/** The label, glyph and colour token for a status, in every surface. */
+export function statusMeta(status: RunStatus | (string & {})): StatusMeta {
+  return META[runStatus(status)];
+}
+
+export interface RunStatusIconProps extends Omit<LucideProps, "ref"> {
+  status: RunStatus | (string & {});
+}
+
+/**
+ * A status glyph on the icon grid, in its token colour and labelled with its
+ * word. Pass `aria-hidden` where the label is already printed beside it.
+ * Running breathes on `--motion-ambient`, the page's one loop period; the
+ * breathe is opacity only, so it is the essential motion reduced motion keeps.
+ */
+export function RunStatusIcon({ status, className, style, ...props }: RunStatusIconProps) {
+  const key = runStatus(status);
+  const { label, icon: Icon, token } = META[key];
+  const running = key === "running";
+  return (
+    <Icon
+      role="img"
+      aria-label={label}
+      size={16}
+      strokeWidth={1.75}
+      data-run-status={key}
+      data-motion={running ? "essential" : undefined}
+      className={cn("shrink-0", running && "animate-[tangle-breathe_var(--motion-ambient)_infinite]", className)}
+      style={{ color: `var(${token})`, ...style }}
+      {...props}
+    />
+  );
+}