@stigmer/react 3.11.0 → 3.12.0

package/src/composer/ConfigureMenu.tsx

@@ -2,6 +2,7 @@
 
 import { cn } from "@stigmer/theme";
 import { Popover } from "@base-ui/react/popover";
+import { Tooltip, TooltipContent, TooltipTrigger } from "../internal/tooltip.js";
 import { useStigmerPortalContainer } from "../portal-container.js";
 import { ConfigureIcon } from "./icons.js";
 
@@ -71,31 +72,39 @@ export function ConfigureMenu({
 
   return (
     <Popover.Root open={open} onOpenChange={handleOpenChange}>
-      <Popover.Trigger
-        disabled={disabled}
-        title="Configure"
-        className={cn(
-          "stg:inline-flex stg:h-8 stg:w-8 stg:items-center stg:justify-center stg:rounded-md stg:text-xs stg:transition-colors",
-          "stg:text-muted-foreground stg:hover:text-foreground stg:hover:bg-accent-hover",
-          "stg:disabled:pointer-events-none stg:disabled:opacity-50",
-        )}
-        aria-label="Configure agent, tools, and skills"
-      >
-        <span className="stg:relative">
-          <ConfigureIcon />
-          {totalCount > 0 && (
-            <span className="stg:absolute stg:-right-1.5 stg:-top-1.5 stg:flex stg:h-3.5 stg:min-w-3.5 stg:items-center stg:justify-center stg:rounded-full stg:bg-primary stg:px-0.5 stg:text-[0.5rem] stg:font-medium stg:leading-none stg:text-primary-foreground">
-              {totalCount}
+      {/* The tooltip trigger is a wrapper span, not the popover trigger
+          itself: `disabled` adds `pointer-events-none` to the button, so
+          only the span keeps hover — the icon's name stays discoverable
+          while the composer is disabled. */}
+      <Tooltip>
+        <TooltipTrigger render={<span className="stg:inline-flex" />}>
+          <Popover.Trigger
+            disabled={disabled}
+            className={cn(
+              "stg:inline-flex stg:h-8 stg:w-8 stg:items-center stg:justify-center stg:rounded-md stg:text-xs stg:transition-colors",
+              "stg:text-muted-foreground stg:hover:text-foreground stg:hover:bg-accent-hover",
+              "stg:disabled:pointer-events-none stg:disabled:opacity-50",
+            )}
+            aria-label="Configure agent, tools, and skills"
+          >
+            <span className="stg:relative">
+              <ConfigureIcon />
+              {totalCount > 0 && (
+                <span className="stg:absolute stg:-right-1.5 stg:-top-1.5 stg:flex stg:h-3.5 stg:min-w-3.5 stg:items-center stg:justify-center stg:rounded-full stg:bg-primary stg:px-0.5 stg:text-[0.5rem] stg:font-medium stg:leading-none stg:text-primary-foreground">
+                  {totalCount}
+                </span>
+              )}
+              {hasWarning && totalCount === 0 && (
+                <span
+                  className="stg:absolute stg:-right-0.5 stg:-top-0.5 stg:inline-block stg:h-2 stg:w-2 stg:rounded-full stg:bg-warning"
+                  aria-label="Configuration needed"
+                />
+              )}
             </span>
-          )}
-          {hasWarning && totalCount === 0 && (
-            <span
-              className="stg:absolute stg:-right-0.5 stg:-top-0.5 stg:inline-block stg:h-2 stg:w-2 stg:rounded-full stg:bg-warning"
-              aria-label="Configuration needed"
-            />
-          )}
-        </span>
-      </Popover.Trigger>
+          </Popover.Trigger>
+        </TooltipTrigger>
+        <TooltipContent side="top">Configure</TooltipContent>
+      </Tooltip>
       <Popover.Portal container={portalContainer}>
         <Popover.Positioner sideOffset={8} align="start">
           <Popover.Popup

package/src/composer/ContextChip.tsx

@@ -1,4 +1,5 @@
 import { cn } from "@stigmer/theme";
+import { TruncatedText } from "../internal/truncated-text.js";
 import { ChipSpinner, XIcon } from "./icons.js";
 
 export interface ChipItem {
@@ -60,9 +61,7 @@ export function ContextChip({
       <span className="stg:text-[0.55rem] stg:font-medium stg:uppercase stg:tracking-wider stg:text-muted-foreground">
         {CHIP_TYPE_LABELS[type]}
       </span>
-      <span className="stg:max-w-[120px] stg:truncate" title={label}>
-        {label}
-      </span>
+      <TruncatedText text={label} className="stg:max-w-[120px]" />
       {detail != null && (
         <span className="stg:shrink-0 stg:text-[0.6rem] stg:font-medium stg:text-muted-foreground">
           {detail}

package/src/composer/ContextPopover.tsx

@@ -1,5 +1,6 @@
 import { cn } from "@stigmer/theme";
 import { Popover } from "@base-ui/react/popover";
+import { Tooltip, TooltipContent, TooltipTrigger } from "../internal/tooltip.js";
 import { useStigmerPortalContainer } from "../portal-container.js";
 
 export function ContextPopover({
@@ -23,25 +24,33 @@ export function ContextPopover({
 
   return (
     <Popover.Root open={open} onOpenChange={onOpenChange}>
-      <Popover.Trigger
-        disabled={disabled}
-        title={label}
-        aria-label={label}
-        className={cn(
-          "stg:inline-flex stg:h-8 stg:w-8 stg:items-center stg:justify-center stg:rounded-md stg:text-xs stg:transition-colors",
-          "stg:text-muted-foreground stg:hover:text-foreground stg:hover:bg-accent-hover",
-          "stg:disabled:pointer-events-none stg:disabled:opacity-50",
-        )}
-      >
-        <span className="stg:relative">
-          {icon}
-          {count > 0 && (
-            <span className="stg:absolute stg:-right-1.5 stg:-top-1.5 stg:flex stg:h-3.5 stg:min-w-3.5 stg:items-center stg:justify-center stg:rounded-full stg:bg-primary stg:px-0.5 stg:text-[0.5rem] stg:font-medium stg:leading-none stg:text-primary-foreground">
-              {count}
+      {/* The tooltip trigger is a wrapper span, not the popover trigger
+          itself: `disabled` adds `pointer-events-none` to the button, so
+          only the span keeps hover — the icon's name stays discoverable
+          while the composer is disabled. */}
+      <Tooltip>
+        <TooltipTrigger render={<span className="stg:inline-flex" />}>
+          <Popover.Trigger
+            disabled={disabled}
+            aria-label={label}
+            className={cn(
+              "stg:inline-flex stg:h-8 stg:w-8 stg:items-center stg:justify-center stg:rounded-md stg:text-xs stg:transition-colors",
+              "stg:text-muted-foreground stg:hover:text-foreground stg:hover:bg-accent-hover",
+              "stg:disabled:pointer-events-none stg:disabled:opacity-50",
+            )}
+          >
+            <span className="stg:relative">
+              {icon}
+              {count > 0 && (
+                <span className="stg:absolute stg:-right-1.5 stg:-top-1.5 stg:flex stg:h-3.5 stg:min-w-3.5 stg:items-center stg:justify-center stg:rounded-full stg:bg-primary stg:px-0.5 stg:text-[0.5rem] stg:font-medium stg:leading-none stg:text-primary-foreground">
+                  {count}
+                </span>
+              )}
             </span>
-          )}
-        </span>
-      </Popover.Trigger>
+          </Popover.Trigger>
+        </TooltipTrigger>
+        <TooltipContent side="top">{label}</TooltipContent>
+      </Tooltip>
       <Popover.Portal container={portalContainer}>
         <Popover.Positioner sideOffset={8} align="start">
           <Popover.Popup

package/src/composer/SessionComposer.tsx

@@ -38,6 +38,7 @@ import {
   resolveSystemEnvVarValues,
 } from "../environment/systemEnvVars.js";
 import { useRenderTracer } from "../internal/dev/index.js";
+import { Tooltip, TooltipContent, TooltipTrigger } from "../internal/tooltip.js";
 import {
   AgentIcon,
   McpServerIcon,
@@ -333,6 +334,20 @@ export interface SessionComposerProps {
    */
   readonly onAgentResolutionChange?: (resolution: AgentResolution | null) => void;
 
+  /**
+   * Called whenever the agent setup's error changes: an {@link Error} when
+   * resolution (or env submission) fails, `null` when the error clears.
+   *
+   * This is the ONLY way an embedder can observe a failed mount-time
+   * resolution of {@link SessionComposerProps.initialAgentRef}: the failure
+   * is captured internally and rendered inside the Configure popover's
+   * agent panel — a surface a locked, end-user-facing embed never opens.
+   * A parent that gates behavior on `onAgentResolutionChange` alone waits
+   * forever on a resolution that already failed; wire this to surface the
+   * reason instead.
+   */
+  readonly onAgentSetupErrorChange?: (error: Error | null) => void;
+
   /**
    * Agent to auto-select when the composer mounts.
    *
@@ -598,6 +613,7 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
   agentRef,
   onAgentRefChange,
   onAgentResolutionChange,
+  onAgentSetupErrorChange,
   initialAgentRef,
   initialInstanceId,
   isDefaultAgent = false,
@@ -718,6 +734,16 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
     onAgentResolutionChange?.(agentSetup.state.resolution);
   }, [agentSetup.state, onAgentResolutionChange]);
 
+  // The error's own bridge, beside the resolution's: the setup error is
+  // orthogonal to phase and is otherwise visible ONLY inside the Configure
+  // popover -- which a locked end-user embed never opens. Without this, a
+  // failed mount-time resolution of initialAgentRef is invisible to the
+  // parent (the resolution callback never fires on failure) and any parent
+  // gate waiting on it holds forever.
+  useEffect(() => {
+    onAgentSetupErrorChange?.(agentSetup.state.error ?? null);
+  }, [agentSetup.state.error, onAgentSetupErrorChange]);
+
   // ---------------------------------------------------------------------------
   // Attachments — file upload state machine
   // ---------------------------------------------------------------------------
@@ -1522,15 +1548,21 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
               Editing message
             </span>
             {onCancelEdit && (
-              <button
-                type="button"
-                onClick={onCancelEdit}
-                aria-label="Cancel editing"
-                title="Cancel editing (Esc)"
-                className="stg:rounded stg:p-0.5 stg:text-muted-foreground stg:transition-colors stg:hover:bg-accent stg:hover:text-foreground stg:focus-visible:outline-none stg:focus-visible:ring-1 stg:focus-visible:ring-ring"
-              >
-                <XIcon />
-              </button>
+              <Tooltip>
+                <TooltipTrigger
+                  render={
+                    <button
+                      type="button"
+                      onClick={onCancelEdit}
+                      aria-label="Cancel editing"
+                      className="stg:rounded stg:p-0.5 stg:text-muted-foreground stg:transition-colors stg:hover:bg-accent stg:hover:text-foreground stg:focus-visible:outline-none stg:focus-visible:ring-1 stg:focus-visible:ring-ring"
+                    />
+                  }
+                >
+                  <XIcon />
+                </TooltipTrigger>
+                <TooltipContent side="top">Cancel editing (Esc)</TooltipContent>
+              </Tooltip>
             )}
           </div>
         )}

package/src/composer/__tests__/SessionComposer-agentSetupError.test.tsx

@@ -0,0 +1,124 @@
+import { describe, it, expect, vi, beforeAll, beforeEach, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { ModelRegistryContext } from "../../models/ModelRegistryContext";
+
+// Without a StigmerProvider the portal container is null, and Base UI's
+// Portal renders nothing — pin it to document.body so popovers can mount.
+vi.mock("../../portal-container", () => ({
+  useStigmerPortalContainer: () => document.body,
+}));
+
+// Controllable agent-setup state — these tests drive the error slot directly
+// instead of exercising the full resolution state machine (covered by
+// useAgentSetup's own tests).
+const mockAgentSetup = {
+  state: { status: "idle", error: null } as Record<string, unknown>,
+  resolveAgent: vi.fn(),
+  resolveToInstance: vi.fn(),
+  submitEnvVars: vi.fn(),
+  reset: vi.fn(),
+};
+vi.mock("../../agent/useAgentSetup", () => ({
+  useAgentSetup: () => mockAgentSetup,
+}));
+
+import { SessionComposer } from "../SessionComposer";
+
+beforeAll(() => {
+  if (!("ResizeObserver" in globalThis)) {
+    (globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver =
+      class {
+        observe() {}
+        unobserve() {}
+        disconnect() {}
+      };
+  }
+});
+
+function createMinimalStigmerMock(): Stigmer {
+  return {
+    agentExecution: { uploadAttachment: vi.fn() },
+    environment: { getPersonal: vi.fn().mockResolvedValue(null) },
+    baseUrl: "http://localhost:8080",
+    getAuthCredential: vi.fn().mockResolvedValue("test-token"),
+    config: {
+      baseUrl: "http://localhost:8080",
+      getAccessToken: vi.fn().mockResolvedValue(""),
+    },
+  } as unknown as Stigmer;
+}
+
+function createWrapper(client: Stigmer) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <StigmerContext.Provider value={client}>
+        <ModelRegistryContext.Provider
+          value={{ models: [], isLoading: false, error: null, refetch: vi.fn() }}
+        >
+          {children}
+        </ModelRegistryContext.Provider>
+      </StigmerContext.Provider>
+    );
+  };
+}
+
+function renderComposer(
+  props?: Partial<React.ComponentProps<typeof SessionComposer>>,
+) {
+  const client = createMinimalStigmerMock();
+  return render(
+    <SessionComposer
+      onSubmit={vi.fn()}
+      org="acme"
+      agentRef={null}
+      onAgentRefChange={vi.fn()}
+      onSkillRefsChange={vi.fn()}
+      skillRefs={[]}
+      {...props}
+    />,
+    { wrapper: createWrapper(client) },
+  );
+}
+
+beforeEach(() => {
+  mockAgentSetup.state = { status: "idle", error: null };
+});
+
+afterEach(cleanup);
+
+/**
+ * The agent setup error's OUTBOUND bridge. The error is otherwise rendered
+ * only inside the Configure popover's agent panel — which a locked,
+ * end-user-facing embed never opens — and onAgentResolutionChange fires only
+ * on success. Without this callback, a failed mount-time resolution of
+ * initialAgentRef is invisible to the parent, and any parent gate waiting on
+ * the resolution holds forever (the "dead launcher pane" class).
+ */
+describe("SessionComposer — onAgentSetupErrorChange", () => {
+  it("reports the setup error to the parent", () => {
+    const onError = vi.fn();
+    const failure = new Error("agent lookup timed out");
+    mockAgentSetup.state = { status: "idle", error: failure };
+
+    renderComposer({ onAgentSetupErrorChange: onError });
+
+    expect(onError).toHaveBeenCalledWith(failure);
+  });
+
+  it("reports null when no error is present (and when it clears)", () => {
+    const onError = vi.fn();
+    renderComposer({ onAgentSetupErrorChange: onError });
+
+    expect(onError).toHaveBeenCalledWith(null);
+    expect(onError).not.toHaveBeenCalledWith(expect.any(Error));
+  });
+
+  it("renders normally when the callback is not provided", () => {
+    mockAgentSetup.state = { status: "idle", error: new Error("boom") };
+
+    expect(() => renderComposer()).not.toThrow();
+  });
+});

package/src/composer/__tests__/SessionComposer-lockAgent.test.tsx

@@ -1,8 +1,9 @@
 import { describe, it, expect, vi, beforeAll, beforeEach, afterEach } from "vitest";
-import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+import { render, screen, cleanup } from "@testing-library/react";
 import type { ReactNode } from "react";
 import type { Stigmer } from "@stigmer/sdk";
 import { StigmerContext } from "../../context";
+import { openMenu } from "../../__tests__/helpers/open-menu";
 import { ModelRegistryContext } from "../../models/ModelRegistryContext";
 
 // Controllable agent-setup state — lets these tests drive the lock × setup
@@ -79,17 +80,11 @@ function renderComposer(
   );
 }
 
-/**
- * Opens the composer's Configure menu and resolves once the portaled menu
- * content mounts. Menu items render asynchronously in a portal, so a
- * synchronous item query straight after the click races the mount (the
- * openRowMenu idiom; see stigmer/stigmer#323).
- */
+/** Opens the composer's Configure menu via the shared readiness-gated helper. */
 async function openConfigureMenu() {
-  fireEvent.click(
+  await openMenu(
     screen.getByRole("button", { name: "Configure agent, tools, and skills" }),
   );
-  await screen.findByRole("menu");
 }
 
 beforeEach(() => {

package/src/conversation/ConversationMediaAttachment.tsx

@@ -10,6 +10,7 @@ import { AttachmentImageLightbox } from "../attachment/AttachmentImageLightbox.j
 import { formatFileSize } from "../attachment/attachment-utils.js";
 import { UNSTYLED_BUTTON } from "../internal/form-primitives.js";
 import { toError } from "../internal/toError.js";
+import { TruncatedText } from "../internal/truncated-text.js";
 import { useStigmer } from "../hooks.js";
 import { useConversationMediaUrl } from "./useConversationMediaUrl.js";
 
@@ -191,7 +192,6 @@ function MediaDocumentChip({
   return (
     <div className={className}>
       <span
-        title={name}
         className="stg:inline-flex stg:max-w-[240px] stg:items-center stg:rounded-md stg:bg-muted-subtle stg:px-2 stg:py-1 stg:text-xs stg:text-foreground"
       >
         <button
@@ -206,7 +206,7 @@ function MediaDocumentChip({
           )}
         >
           <FileGlyph />
-          <span className="stg:min-w-0 stg:truncate">{name}</span>
+          <TruncatedText text={name} className="stg:min-w-0" />
           {size !== null && (
             <span className="stg:shrink-0 stg:text-muted-foreground">{size}</span>
           )}

package/src/conversation/ConversationTimelineView.tsx

@@ -19,6 +19,7 @@ import {
 import { useAutoScroll } from "../internal/useAutoScroll.js";
 import { ConversationMediaAttachment } from "./ConversationMediaAttachment.js";
 import {
+  attemptExplanationOf,
   authorKindOf,
   inboundPlaceholderOf,
   isInternalItem,
@@ -228,8 +229,10 @@ const TimelineItemRow = memo(function TimelineItemRow({
   // relay, never pattern-matched; the numeric twin (receipt_error_code)
   // stays off the surface as machine vocabulary. Gated exactly like
   // ReceiptTicks' failed arm — attempt delivered AND receipt failed —
-  // so the attempt-axis explanation (last_error, F-25's slice) can
-  // structurally never leak in here.
+  // so the attempt-axis explanation (attemptExplanationOf, cloud#262's
+  // slice) can structurally never leak in here: its gate requires
+  // attempt FAILED, this one attempt delivered, so at most one of the
+  // two explanations ever renders.
   const receiptExplanation =
     sendAttemptOf(item) === "delivered" &&
     receiptOf(item) === "failed" &&
@@ -237,6 +240,15 @@ const TimelineItemRow = memo(function TimelineItemRow({
       ? item.receiptDetail
       : null;
 
+  // The attempt axis's explanation (cloud#262, closing F-25), the same
+  // R-1 visible-text treatment as the receipt explanation and for the
+  // same reason: why a send failed is decision-bearing (a closed
+  // 24h-window refusal says "the customer must write first"; a deleted
+  // channel says there is nothing to retry). The words and the gate
+  // live in attemptExplanationOf — presentation vocabulary, never
+  // computed in the view.
+  const attemptExplanation = attemptExplanationOf(item);
+
   return (
     <li className={cn("stg:flex", isCustomer ? "stg:justify-start" : "stg:justify-end")}>
       <div
@@ -274,6 +286,11 @@ const TimelineItemRow = memo(function TimelineItemRow({
             {receiptExplanation}
           </p>
         )}
+        {attemptExplanation !== null && (
+          <p className="stg:mt-1 stg:break-words stg:text-xs stg:text-destructive">
+            {attemptExplanation}
+          </p>
+        )}
         <ItemFooter item={item} />
       </div>
     </li>

package/src/conversation/__tests__/ConversationTimelineView.test.tsx

@@ -10,7 +10,10 @@ import {
   ConversationLane,
   ConversationTimelineItemSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
-import { ChannelDeliveryStatus } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/delivery_pb";
+import {
+  ChannelAttemptFailureKind,
+  ChannelDeliveryStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/delivery_pb";
 import { ChannelReceiptState } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/outbound_pb";
 import { StigmerContext } from "../../context";
 import { ConversationTimelineView } from "../ConversationTimelineView";
@@ -174,8 +177,9 @@ describe("ConversationTimelineView", () => {
             text: "lost reply",
             deliveryStatus: ChannelDeliveryStatus.failed,
             // A malformed item carrying a detail on the wrong axis: the
-            // attempt-axis explanation (last_error) is F-25's separate
-            // slice, so this lane renders nothing extra.
+            // attempt-axis explanation has its own field and gate
+            // (attemptExplanationOf, cloud#262), so a stray receipt
+            // detail still renders nothing here.
             receiptDetail: "should never render",
           }),
         ]}
@@ -185,6 +189,105 @@ describe("ConversationTimelineView", () => {
     expect(screen.queryByText("should never render")).toBeNull();
   });
 
+  it("shows a refused send's platform-authored explanation verbatim (cloud#262)", () => {
+    render(
+      <ConversationTimelineView
+        {...baseProps()}
+        items={[
+          item("ob:1", {
+            author: ConversationItemAuthor.author_teammate,
+            text: "Following up on your case.",
+            deliveryStatus: ChannelDeliveryStatus.failed,
+            attemptFailureKind: ChannelAttemptFailureKind.attempt_refused,
+            attemptDetail: "the recipient's 24-hour customer-service window is closed",
+          }),
+        ]}
+      />,
+    );
+    expect(screen.getByText("Not delivered")).toBeDefined();
+    expect(
+      screen.getByText("the recipient's 24-hour customer-service window is closed"),
+    ).toBeDefined();
+  });
+
+  it("shows a withdrawn send's structural fact verbatim (cloud#262)", () => {
+    render(
+      <ConversationTimelineView
+        {...baseProps()}
+        items={[
+          item("dl:1", {
+            author: ConversationItemAuthor.author_agent,
+            text: "the reply that never landed",
+            deliveryStatus: ChannelDeliveryStatus.failed,
+            attemptFailureKind: ChannelAttemptFailureKind.attempt_withdrawn,
+            attemptDetail: "channel deleted",
+          }),
+        ]}
+      />,
+    );
+    expect(screen.getByText("channel deleted")).toBeDefined();
+  });
+
+  it("shows this surface's own generic copy for an errored send — the wire carries no detail (cloud#262)", () => {
+    render(
+      <ConversationTimelineView
+        {...baseProps()}
+        items={[
+          item("dl:1", {
+            author: ConversationItemAuthor.author_agent,
+            text: "lost reply",
+            deliveryStatus: ChannelDeliveryStatus.failed,
+            attemptFailureKind: ChannelAttemptFailureKind.attempt_errored,
+            // attemptDetail deliberately empty: the server's AttemptFailure
+            // construction keeps diagnostics off the wire entirely.
+          }),
+        ]}
+      />,
+    );
+    expect(screen.getByText("Not delivered")).toBeDefined();
+    expect(
+      screen.getByText("Delivery failed due to a technical problem on the platform's side."),
+    ).toBeDefined();
+  });
+
+  it("keeps the bare tick for a failure the platform never classified (pre-cloud#262 rows)", () => {
+    render(
+      <ConversationTimelineView
+        {...baseProps()}
+        items={[
+          item("ob:1", {
+            author: ConversationItemAuthor.author_teammate,
+            text: "an old failed send",
+            deliveryStatus: ChannelDeliveryStatus.failed,
+          }),
+        ]}
+      />,
+    );
+    expect(screen.getByText("Not delivered")).toBeDefined();
+    expect(screen.queryByText(/technical problem/)).toBeNull();
+  });
+
+  it("never shows the attempt explanation on a delivered item — the F-25 boundary's mirror", () => {
+    render(
+      <ConversationTimelineView
+        {...baseProps()}
+        items={[
+          item("ob:1", {
+            author: ConversationItemAuthor.author_teammate,
+            text: "a landed send",
+            deliveryStatus: ChannelDeliveryStatus.delivered,
+            // A malformed item carrying attempt copy on a success: the
+            // gate requires attempt FAILED, so nothing renders.
+            attemptFailureKind: ChannelAttemptFailureKind.attempt_refused,
+            attemptDetail: "should never render",
+          }),
+        ]}
+      />,
+    );
+    expect(screen.queryByText("should never render")).toBeNull();
+    expect(screen.queryByText("Not delivered")).toBeNull();
+  });
+
   it("renders a dead-lettered send as exactly that", () => {
     render(
       <ConversationTimelineView

package/src/conversation/conversationPresentation.ts

@@ -6,7 +6,10 @@ import {
   ConversationLane,
   type ConversationTimelineItem,
 } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
-import { ChannelDeliveryStatus } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/delivery_pb";
+import {
+  ChannelAttemptFailureKind,
+  ChannelDeliveryStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/delivery_pb";
 import { ChannelReceiptState } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/outbound_pb";
 import type { ChannelProviderId } from "../channel/providers.js";
 
@@ -106,6 +109,54 @@ export function receiptOf(item: ConversationTimelineItem): ReceiptKind | null {
   }
 }
 
+/**
+ * Why a FAILED send attempt failed, in render vocabulary. `null` until
+ * the platform classifies (rows failed before the classification
+ * existed, and every non-failed item).
+ *
+ * The structured twin of {@link attemptExplanationOf}'s prose
+ * (cloud#262): a renderer that branches on the failure keys on this,
+ * never on the explanation's words.
+ */
+export type AttemptFailureKind = "refused" | "errored" | "withdrawn";
+
+/** Map the wire attempt-failure kind onto the render vocabulary. */
+export function attemptFailureOf(item: ConversationTimelineItem): AttemptFailureKind | null {
+  switch (item.attemptFailureKind) {
+    case ChannelAttemptFailureKind.attempt_refused:
+      return "refused";
+    case ChannelAttemptFailureKind.attempt_errored:
+      return "errored";
+    case ChannelAttemptFailureKind.attempt_withdrawn:
+      return "withdrawn";
+    default:
+      return null;
+  }
+}
+
+/**
+ * The visible explanation for a FAILED send attempt, or `null` when the
+ * item carries none to show (non-failed items, and rows failed before
+ * the platform classified failures).
+ *
+ * The attempt-axis sibling of the receipt explanation (cloud#262,
+ * closing F-25): `attempt_detail` is PLATFORM-authored thread-safe copy
+ * — the write side guarantees raw diagnostics never occupy it — so it
+ * renders verbatim when present (refusals and withdrawn sends). An
+ * `errored` failure deliberately carries no detail (its diagnostic is
+ * operator-only, in `last_error` server-side); the copy here is this
+ * surface's own generic for that arm, and it makes NO claim about
+ * attempt counts — the wire does not carry them, and `errored` covers
+ * first-try structural dead-letters as well as exhausted retries.
+ */
+export function attemptExplanationOf(item: ConversationTimelineItem): string | null {
+  if (sendAttemptOf(item) !== "failed") return null;
+  if (item.attemptDetail !== "") return item.attemptDetail;
+  return attemptFailureOf(item) === "errored"
+    ? "Delivery failed due to a technical problem on the platform's side."
+    : null;
+}
+
 /**
  * Placeholder copy for inbound items whose body the platform cannot
  * render (`text` empty, `provider_message_type` names the kind) — the