@stigmer/react 3.10.0 → 3.11.1-dev.20260812192248

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";
 
@@ -115,32 +116,32 @@ function MediaImageThumbnail({
 
   return (
     <>
-      {/* UNSTYLED_BUTTON is load-bearing: without it the thumbnail shows
-          the UA's default button box in preflight-less hosts. */}
+      {/* UNSTYLED_BUTTON adds the pointer cursor — the media thumbnail
+          carries no other clickability cue. */}
       <button
         type="button"
         onClick={() => setPreviewOpen(true)}
         aria-label={`Preview ${name}`}
         className={cn(
           UNSTYLED_BUTTON,
-          "block rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          "stg:block stg:rounded-md stg:focus-visible:outline-none stg:focus-visible:ring-2 stg:focus-visible:ring-ring",
           className,
         )}
       >
-        <span className="relative block h-40 w-56 max-w-full overflow-hidden rounded-md">
+        <span className="stg:relative stg:block stg:h-40 stg:w-56 stg:max-w-full stg:overflow-hidden stg:rounded-md">
           {url ? (
             <img
               src={url}
               alt=""
               aria-hidden="true"
               loading="lazy"
-              className="h-full w-full object-cover"
+              className="stg:h-full stg:w-full stg:object-cover"
             />
           ) : (
             // Pulse placeholder while the presigned URL is minted; same
             // footprint as the image, so no layout shift.
             <span
-              className="block h-full w-full animate-pulse bg-muted"
+              className="stg:block stg:h-full stg:w-full stg:animate-pulse stg:bg-muted"
               aria-hidden="true"
             />
           )}
@@ -191,8 +192,7 @@ function MediaDocumentChip({
   return (
     <div className={className}>
       <span
-        title={name}
-        className="inline-flex max-w-[240px] items-center rounded-md bg-muted-subtle px-2 py-1 text-xs text-foreground"
+        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
           type="button"
@@ -201,19 +201,19 @@ function MediaDocumentChip({
           aria-label={`Open ${name}`}
           className={cn(
             UNSTYLED_BUTTON,
-            "flex min-w-0 items-center gap-1.5 rounded-sm text-inherit [font:inherit] hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
-            isOpening && "opacity-70",
+            "stg:flex stg:min-w-0 stg:items-center stg:gap-1.5 stg:rounded-sm stg:hover:text-accent-foreground stg:focus-visible:outline-none stg:focus-visible:ring-2 stg:focus-visible:ring-ring",
+            isOpening && "stg:opacity-70",
           )}
         >
           <FileGlyph />
-          <span className="min-w-0 truncate">{name}</span>
+          <TruncatedText text={name} className="stg:min-w-0" />
           {size !== null && (
-            <span className="shrink-0 text-muted-foreground">{size}</span>
+            <span className="stg:shrink-0 stg:text-muted-foreground">{size}</span>
           )}
         </button>
       </span>
       {error !== null && (
-        <p className="mt-1 break-words text-xs text-destructive">
+        <p className="stg:mt-1 stg:break-words stg:text-xs stg:text-destructive">
           {getUserMessage(error)}
         </p>
       )}
@@ -298,7 +298,7 @@ function FileGlyph() {
       strokeWidth="1.5"
       strokeLinecap="round"
       strokeLinejoin="round"
-      className="shrink-0 text-muted-foreground"
+      className="stg:shrink-0 stg:text-muted-foreground"
       aria-hidden="true"
     >
       <path d="M8 1H4C3.45 1 3 1.45 3 2V12C3 12.55 3.45 13 4 13H10C10.55 13 11 12.55 11 12V4L8 1Z" />

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,
@@ -113,15 +114,15 @@ export function ConversationTimelineView({
     <TooltipProvider>
       <div
         aria-label="Conversation timeline"
-        className={cn("relative flex min-h-0 flex-1 flex-col", className)}
+        className={cn("stg:relative stg:flex stg:min-h-0 stg:flex-1 stg:flex-col", className)}
       >
         <div
           ref={scrollRef}
-          className="min-h-0 flex-1 overflow-y-auto [overflow-anchor:none] px-4 py-3"
+          className="stg:min-h-0 stg:flex-1 stg:overflow-y-auto stg:[overflow-anchor:none] stg:px-4 stg:py-3"
         >
           {!showsCustomerMessages && descriptor && (
-            <div className="mb-3 flex items-start gap-2 rounded-md border border-border bg-muted-faint px-3 py-2 text-xs text-muted-foreground">
-              <Info aria-hidden="true" className="mt-0.5 size-3.5 shrink-0" />
+            <div className="stg:mb-3 stg:flex stg:items-start stg:gap-2 stg:rounded-md stg:border stg:border-border stg:bg-muted-faint stg:px-3 stg:py-2 stg:text-xs stg:text-muted-foreground">
+              <Info aria-hidden="true" className="stg:mt-0.5 stg:size-3.5 stg:shrink-0" />
               <p>
                 Customer messages on {descriptor.label} channels aren&apos;t shown
                 here yet — this thread has replies, sends, and internal events only.
@@ -132,20 +133,20 @@ export function ConversationTimelineView({
           {isLoading ? (
             <TimelineSkeleton />
           ) : error ? (
-            <p className="px-2 py-6 text-center text-sm text-destructive">
+            <p className="stg:px-2 stg:py-6 stg:text-center stg:text-sm stg:text-destructive">
               {getUserMessage(error)}
             </p>
           ) : items.length === 0 ? (
             <EmptyState
               variant="first-use"
-              icon={<MessageSquare className="size-8" />}
+              icon={<MessageSquare className="stg:size-8" />}
               title="No messages yet"
               description="The conversation's messages appear here as they happen."
             />
           ) : (
             <div ref={contentRef}>
               {hasOlder && (
-                <div className="flex justify-center pb-2">
+                <div className="stg:flex stg:justify-center stg:pb-2">
                   <Button
                     variant="ghost"
                     size="xs"
@@ -159,12 +160,12 @@ export function ConversationTimelineView({
               {days.map((day) => (
                 <div key={day.label}>
                   <div
-                    className="my-2 text-center text-xs text-muted-foreground-faint"
+                    className="stg:my-2 stg:text-center stg:text-xs stg:text-muted-foreground-faint"
                     role="separator"
                   >
                     {day.label}
                   </div>
-                  <ul className="space-y-1.5">
+                  <ul className="stg:space-y-1.5">
                     {day.items.map((item) => (
                       <TimelineItemRow
                         key={item.itemId}
@@ -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,16 +240,25 @@ 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("flex", isCustomer ? "justify-start" : "justify-end")}>
+    <li className={cn("stg:flex", isCustomer ? "stg:justify-start" : "stg:justify-end")}>
       <div
         className={cn(
-          "max-w-[80%] rounded-lg px-3 py-2",
-          isCustomer ? "bg-muted-subtle" : "bg-primary-subtle",
+          "stg:max-w-[80%] stg:rounded-lg stg:px-3 stg:py-2",
+          isCustomer ? "stg:bg-muted-subtle" : "stg:bg-primary-subtle",
         )}
       >
         {!isCustomer && (
-          <p className="text-xs font-medium text-muted-foreground">
+          <p className="stg:text-xs stg:font-medium stg:text-muted-foreground">
             {BUSINESS_CAPTION[author]}
           </p>
         )}
@@ -254,7 +266,7 @@ const TimelineItemRow = memo(function TimelineItemRow({
           <ConversationMediaAttachment
             media={item.media}
             address={mediaAddress}
-            className={item.text ? "mb-1.5" : undefined}
+            className={item.text ? "stg:mb-1.5" : undefined}
           />
         )}
         {/* A media item without a caption is complete as its media —
@@ -262,18 +274,23 @@ const TimelineItemRow = memo(function TimelineItemRow({
         {(body || mediaAddress === null) && (
           <p
             className={cn(
-              "whitespace-pre-wrap break-words text-sm text-foreground",
-              !item.text && "italic text-muted-foreground",
+              "stg:whitespace-pre-wrap stg:break-words stg:text-sm stg:text-foreground",
+              !item.text && "stg:italic stg:text-muted-foreground",
             )}
           >
             {body || "Message content unavailable"}
           </p>
         )}
         {receiptExplanation !== null && (
-          <p className="mt-1 break-words text-xs text-destructive">
+          <p className="stg:mt-1 stg:break-words stg:text-xs stg:text-destructive">
             {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>
@@ -323,30 +340,30 @@ function ItemFooter({ item }: { readonly item: ConversationTimelineItem }) {
     : "";
 
   return (
-    <p className="mt-1 flex items-center justify-end gap-1 text-xs text-muted-foreground-faint">
+    <p className="stg:mt-1 stg:flex stg:items-center stg:justify-end stg:gap-1 stg:text-xs stg:text-muted-foreground-faint">
       <span>{time}</span>
       {attempt === "failed" && (
         <StatusHint
           hint="The platform could not deliver this message"
-          className="flex items-center gap-0.5 text-destructive"
+          className="stg:flex stg:items-center stg:gap-0.5 stg:text-destructive"
         >
-          <TriangleAlert aria-hidden="true" className="size-3" />
+          <TriangleAlert aria-hidden="true" className="stg:size-3" />
           Not delivered
         </StatusHint>
       )}
       {attempt === "suppressed" && (
         <StatusHint
           hint="Withheld because a human had the conversation when it came due"
-          className="flex items-center gap-0.5"
+          className="stg:flex stg:items-center stg:gap-0.5"
         >
-          <Ban aria-hidden="true" className="size-3" />
+          <Ban aria-hidden="true" className="stg:size-3" />
           Held
         </StatusHint>
       )}
       {(attempt === "pending" || attempt === "delivering") && (
-        <StatusHint hint="Sending" className="flex items-center gap-0.5">
-          <Clock aria-hidden="true" className="size-3" />
-          <span className="sr-only">Sending</span>
+        <StatusHint hint="Sending" className="stg:flex stg:items-center stg:gap-0.5">
+          <Clock aria-hidden="true" className="stg:size-3" />
+          <span className="stg:sr-only">Sending</span>
         </StatusHint>
       )}
       {attempt === "delivered" && <ReceiptTicks item={item} />}
@@ -366,34 +383,34 @@ function ReceiptTicks({ item }: { readonly item: ConversationTimelineItem }) {
     return (
       <StatusHint
         hint="The provider accepted this message but could not deliver it"
-        className="flex items-center gap-0.5 text-destructive"
+        className="stg:flex stg:items-center stg:gap-0.5 stg:text-destructive"
       >
-        <TriangleAlert aria-hidden="true" className="size-3" />
+        <TriangleAlert aria-hidden="true" className="stg:size-3" />
         Delivery failed
       </StatusHint>
     );
   }
   if (receipt === "read") {
     return (
-      <StatusHint hint="Read by the customer" className="text-primary">
-        <CheckCheck aria-hidden="true" className="size-3.5" />
-        <span className="sr-only">Read</span>
+      <StatusHint hint="Read by the customer" className="stg:text-primary">
+        <CheckCheck aria-hidden="true" className="stg:size-3.5" />
+        <span className="stg:sr-only">Read</span>
       </StatusHint>
     );
   }
   if (receipt === "delivered") {
     return (
       <StatusHint hint="Delivered to the customer's device">
-        <CheckCheck aria-hidden="true" className="size-3.5" />
-        <span className="sr-only">Delivered</span>
+        <CheckCheck aria-hidden="true" className="stg:size-3.5" />
+        <span className="stg:sr-only">Delivered</span>
       </StatusHint>
     );
   }
   // Handed to the provider; no (further) receipt yet.
   return (
     <StatusHint hint="Sent">
-      <Check aria-hidden="true" className="size-3.5" />
-      <span className="sr-only">Sent</span>
+      <Check aria-hidden="true" className="stg:size-3.5" />
+      <span className="stg:sr-only">Sent</span>
     </StatusHint>
   );
 }
@@ -409,25 +426,25 @@ function InternalEventRow({ item }: { readonly item: ConversationTimelineItem })
   const isEscalation = author === "agent" && item.text !== "";
 
   return (
-    <li className="flex justify-center">
+    <li className="stg:flex stg:justify-center">
       <div
         className={cn(
-          "flex max-w-[90%] items-start gap-1.5 rounded-md px-3 py-1.5 text-center text-xs",
+          "stg:flex stg:max-w-[90%] stg:items-start stg:gap-1.5 stg:rounded-md stg:px-3 stg:py-1.5 stg:text-center stg:text-xs",
           isEscalation
-            ? "bg-destructive-subtle text-destructive"
-            : "bg-muted-faint text-muted-foreground",
+            ? "stg:bg-destructive-subtle stg:text-destructive"
+            : "stg:bg-muted-faint stg:text-muted-foreground",
         )}
       >
         {isEscalation ? (
           <>
-            <TriangleAlert aria-hidden="true" className="mt-0.5 size-3.5 shrink-0" />
-            <span className="min-w-0 break-words">
+            <TriangleAlert aria-hidden="true" className="stg:mt-0.5 stg:size-3.5 stg:shrink-0" />
+            <span className="stg:min-w-0 stg:break-words">
               Agent escalated to a human — “{item.text}”
             </span>
           </>
         ) : item.text !== "" ? (
           // A future internal note flows through with zero code change.
-          <span className="min-w-0 break-words">{item.text}</span>
+          <span className="stg:min-w-0 stg:break-words">{item.text}</span>
         ) : (
           <span>A teammate resolved the attention flag</span>
         )}
@@ -438,10 +455,10 @@ function InternalEventRow({ item }: { readonly item: ConversationTimelineItem })
 
 function TimelineSkeleton() {
   return (
-    <div className="space-y-2" aria-hidden="true">
-      <div className="h-10 w-3/5 animate-pulse rounded-lg bg-muted-faint" />
-      <div className="ml-auto h-10 w-3/5 animate-pulse rounded-lg bg-muted-faint" />
-      <div className="h-10 w-2/5 animate-pulse rounded-lg bg-muted-faint" />
+    <div className="stg:space-y-2" aria-hidden="true">
+      <div className="stg:h-10 stg:w-3/5 stg:animate-pulse stg:rounded-lg stg:bg-muted-faint" />
+      <div className="stg:ml-auto stg:h-10 stg:w-3/5 stg:animate-pulse stg:rounded-lg stg:bg-muted-faint" />
+      <div className="stg:h-10 stg:w-2/5 stg:animate-pulse stg:rounded-lg stg:bg-muted-faint" />
     </div>
   );
 }

package/src/conversation/ConversationsWorkbench.tsx

@@ -265,10 +265,10 @@ export function ConversationsWorkbench({
   return (
     <div
       aria-label="Conversations workbench"
-      className={cn("flex min-h-0 flex-1", className)}
+      className={cn("stg:flex stg:min-h-0 stg:flex-1", className)}
     >
       <ConversationListPane
-        className="w-80 shrink-0 border-r border-border"
+        className="stg:w-80 stg:shrink-0 stg:border-r stg:border-border"
         conversations={list.conversations}
         isLoading={list.isLoading}
         error={list.error}
@@ -286,10 +286,10 @@ export function ConversationsWorkbench({
       />
 
       {selected === null ? (
-        <div className="flex min-w-0 flex-1 items-center justify-center p-6">
+        <div className="stg:flex stg:min-w-0 stg:flex-1 stg:items-center stg:justify-center stg:p-6">
           <EmptyState
             variant="first-use"
-            icon={<MessagesSquare className="size-8" />}
+            icon={<MessagesSquare className="stg:size-8" />}
             title="Select a conversation"
             description="Pick a conversation to read its thread, reply as your business, or take over from the agent."
           />
@@ -305,15 +305,15 @@ export function ConversationsWorkbench({
         // Channel ids never contain ":", so the joined key is unambiguous.
         <div
           key={`${selected.agentChannelId}:${selected.conversationKey}`}
-          className="flex min-w-0 flex-1 flex-col"
+          className="stg:flex stg:min-w-0 stg:flex-1 stg:flex-col"
         >
-          <div className="flex items-center justify-between gap-2 border-b border-border px-4 py-2.5">
-            <div className="min-w-0">
-              <h2 className="truncate text-sm font-semibold text-foreground">
+          <div className="stg:flex stg:items-center stg:justify-between stg:gap-2 stg:border-b stg:border-border stg:px-4 stg:py-2.5">
+            <div className="stg:min-w-0">
+              <h2 className="stg:truncate stg:text-sm stg:font-semibold stg:text-foreground">
                 {detailLabel}
               </h2>
               {(detailContact !== null || channelName) && (
-                <p className="truncate text-xs text-muted-foreground">
+                <p className="stg:truncate stg:text-xs stg:text-muted-foreground">
                   {detailContact}
                   {detailContact !== null && channelName && " · "}
                   {channelName &&
@@ -323,7 +323,7 @@ export function ConversationsWorkbench({
                     (selectedChannelHref ? (
                       <a
                         href={selectedChannelHref}
-                        className="hover:text-foreground hover:underline"
+                        className="stg:hover:text-foreground stg:hover:underline"
                       >
                         {channelName}
                       </a>

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

@@ -85,7 +85,7 @@ describe("ConversationComposer", () => {
     expect(button.textContent).toContain("Sending…");
     // The house in-flight glyph (the session composer's pattern): the
     // static Send icon must not render while the reply is in flight.
-    expect(button.querySelector("svg.animate-spin")).not.toBeNull();
+    expect(button.querySelector("svg.stg\\:animate-spin")).not.toBeNull();
     expect(
       (screen.getByLabelText("Reply to the customer") as HTMLTextAreaElement).disabled,
     ).toBe(true);

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