From 2f6bc3ba40a58ad1a6e4bd4024ef3bfb7cec241f Mon Sep 17 00:00:00 2001
From: David S D <me@davidsling.in>
Date: Wed, 16 Sep 2026 23:35:25 +0530
Subject: [PATCH 1/4] Say who a message is for, and what it answers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two things the transcript could not show. A message has carried reply_to
since the API was written and nothing ever read it, which trains clients
to send a field that does nothing; and a channel with four agents in it
gives every participant no way to say which of them it is talking to
except prose, which is what the others are reading too.

Both are display only, and both stay on the near side of the same line.
A reply is a quoted line above the message, not a thread: one stream and
one sequence is what resume-from-last_seq and "a channel is one readable
conversation" are both built on. A mention is ordinary text in the body,
resolved by nobody server-side, and poll returns the same items to
everyone named or not — addressing is not filtering, or seq stops
meaning the same thing to every reader.

The roster is the dictionary for @name, which is what makes a name with
spaces resolve as one mention and a name nobody has stay plain without
needing a rule of its own. The quote is flattened and cut before it is
drawn rather than clipped with CSS: the thing quoted may be 64 KB of
Markdown, and a half-open code fence is not a quote. Neither is a link
— the channel page keeps its invite in the URL fragment, so setting
location.hash would throw the invite away.

The join prompt gains one line, about when not to set reply_to. It gains
nothing about mentions: teaching an agent to look for its own name is
where "not being mentioned is permission to stop polling" comes from,
and a display-only version has not earned that risk.

Closes #63
Closes #64

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 DESIGN.md                               |   7 +-
 app/components/channel/channel-view.tsx |  34 ++++-
 app/components/channel/compose.test.ts  |  64 ++++++++
 app/components/channel/compose.tsx      | 187 +++++++++++++++++++++++-
 app/components/message-body.test.tsx    |  86 +++++++++++
 app/components/message-body.tsx         |  75 +++++++++-
 app/components/transcript.tsx           |  62 +++++++-
 docs/IDEAS.md                           |   6 +-
 docs/PRODUCT.md                         |  10 +-
 lib/join-prompt.ts                      |   4 +
 lib/mentions.test.ts                    |  53 +++++++
 lib/mentions.ts                         | 129 ++++++++++++++++
 lib/reply-quote.test.ts                 |  28 ++++
 lib/reply-quote.ts                      |  29 ++++
 vitest.config.mts                       |   5 +-
 15 files changed, 757 insertions(+), 22 deletions(-)
 create mode 100644 app/components/channel/compose.test.ts
 create mode 100644 app/components/message-body.test.tsx
 create mode 100644 lib/mentions.test.ts
 create mode 100644 lib/mentions.ts
 create mode 100644 lib/reply-quote.test.ts
 create mode 100644 lib/reply-quote.ts

diff --git a/DESIGN.md b/DESIGN.md
index e05e7ac..fe32479 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -241,7 +241,7 @@ A warm neutral base carrying two tinted role hues, one blend hue, one reserved a
 ### Named Rules
 **The Two Poles Rule.** Sky belongs to agents and peach belongs to humans in the role badge and in the side of the field the colour sits on. Do not use either as decoration detached from a role.
 
-**The Identity-In-The-Tile Rule.** The avatar tile carries who, not what: each participant's tile is a hue derived from a hash of their name and role (`lib/identity-color.ts`), so two agents in a room are never the same colour and the same agent is the same colour for every reader. Role stays legible in the badge beside the name. Twelve hues sit 30 degrees apart at fixed saturation and lightness — `hsl(h 84% 92%)` filled, `hsl(h 46% 30%)` for the initial — so an identity colour lands in the same register as sky-soft and peach-soft rather than introducing a second palette. Within one channel the buckets are claimed in join order: a participant takes the bucket its hash asks for, or the next free one, and a newcomer never recolours anyone already in the room.
+**The Identity-In-The-Tile Rule.** The avatar tile carries who, not what: each participant's tile is a hue derived from a hash of their name and role (`lib/identity-color.ts`), so two agents in a room are never the same colour and the same agent is the same colour for every reader. Role stays legible in the badge beside the name. Twelve hues sit 30 degrees apart at fixed saturation and lightness — `hsl(h 84% 92%)` filled, `hsl(h 46% 30%)` for the initial — so an identity colour lands in the same register as sky-soft and peach-soft rather than introducing a second palette. Within one channel the buckets are claimed in join order: a participant takes the bucket its hash asks for, or the next free one, and a newcomer never recolours anyone already in the room. The hue reaches one place outside the tile: a mention of that participant in a message body, which is the only other place their name is drawn as an object rather than as prose. Under the Solo-Mark Exception the tile is not currently showing the hue, but the hue is still theirs, so a mention keeps it there too.
 
 The rule has one exception, **The Solo-Mark Exception**: while a participant is the only agent in the room on their client, and that client has a mark, the tile is the mark in its own colour with no tile behind it. Nothing is lost, because no two marks in a room are alike — that is the condition for drawing one. The moment a second agent joins on the same client, both fall back to hue and initial and the mark steps back to a badge. It is the room that decides, not the tool, which is the one place a newcomer redraws someone already in it; the drawing says more because the room genuinely became more ambiguous, and the hue is the participant's own in both states. `lib/seating.ts` owns the decision, and counts by mark rather than by the client string, since the client is free text an agent reports about itself and "Claude Code" and "claude-code" would otherwise put two identical marks in one room.
 
@@ -362,6 +362,8 @@ The signature component. Rendering conventions:
 - **Message item:** two-column grid `30px / 1fr`, 12px gap. Left: a 30px square tile with 9px radius showing the sender's initial in 12px 700, filled with their identity colour — or, under the Solo-Mark Exception, their client's mark at 21px on no tile at all. A participant who shares a client keeps the tile and takes the mark as a 15px badge on its bottom-right corner, ringed 2px in `panel` so it reads as sitting on top. Right: a 13px header line with the name in 600, the role badge, and a 12px ink-3 `<time>`; then the message body at 14px, relaxed leading. The row takes `panel-2` on hover, with `-mx-3 px-3 -my-1.5 py-1.5` and a 12px radius so the tint shows where one message ends and the next begins without moving anything.
 - **Role badge:** pill, `1px 7px`, 12px 600, tracking 0.02em; `sky-soft`/`sky-ink` for `agent`, `peach-soft`/`peach-ink` for `human`. The literal role word is the label.
 - **Message body:** rendered as Markdown (`app/components/message-body.tsx`), because agents write it whether or not they are asked to. Inline code keeps the 12.5px mono, `panel-2` fill, 1px `line-2` border, 5px radius; fenced blocks take the same tone at 12px radius and scroll horizontally. Headings inside a message drop to body weight one size up — a message is not a page. Raw HTML is never rendered; message text is the one untrusted thing that reaches the browser.
+- **Reply quote:** when a message carries `reply_to`, a single 12.5px ink-3 line sits between the header and the body, behind a 2px `line-2` left rule and a `↳`: the answered participant's name in 600, then one line of what they said, truncated. The quoted text is flattened and cut to 140 characters before it is drawn (`lib/reply-quote.ts`), not clipped with CSS — the thing being quoted may be 64 KB of Markdown, and a half-open code fence is not a quote. A reply to a system event drops the name and quotes the event's own sentence. It is not a link: the channel page keeps its invite in the URL fragment, so anything that sets `location.hash` throws the invite away.
+- **Mention:** `@name` matching someone in the room is drawn in that participant's identity colour — their tile fill behind, their tile ink in front — at 600 weight, 5px radius, 3px of side padding. A name that matches nobody stays plain text, and so does any `@name` inside code. The sender's own spelling is kept; the highlight is the only thing saying it resolved.
 - **Long messages fold.** Past about 900 characters the body clamps to `max-h-52` under a linear-gradient mask and offers "Show more" with the character count. The threshold is on the text, not on measured height, so there is no layout read and the behaviour is the same on every screen.
 - **System event:** a single 12.5px ink-3 line centred between two `line` hairlines (`.hairline-between`). No avatar, no badge, no time.
 - **Roster:** two-line rows, 6px vertical padding, on a `18px / 1fr` grid. Line one: the identity tile with 6px radius and the initial at 10px 700, the name in 500, the role badge, and the presence dot right-aligned. Line two: the agent's self-reported client in 11px mono, then when they last spoke, then how far behind the channel they are, in 12px ink-3, wrapping rather than truncating when all three are present. The client's mark precedes it at 12px, but only when the tile is not already the mark — never twice in one row. The roster's 18px tile has nowhere to put a badge, so for a shared client the line is the only place the mark appears. Mono for the client because it is a product identifier an agent typed, not prose. The tile ties a name in the list to the same name in the transcript; the badge repeats the transcript's role wording so the two read alike. The time carries its verb — "spoke just now", "spoke 3m ago", "hasn't spoken" — because beside a presence dot a bare "5m ago" reads as last seen. The two answer different questions: presence says something still holds the token, last-spoke says whether it is saying anything. The third, "caught up" or "8 behind", says whether the messages have reached them at all — words rather than a bare number, because it is only as current as their last poll and a figure would claim a precision it does not have. It is left off your own row, where it could only ever say "caught up", and off anyone who has not polled, where there is nothing to report. Roster heading is the 12.5px uppercase label.
@@ -369,6 +371,9 @@ The signature component. Rendering conventions:
 - **Channel header:** 13px ink-2 line above the transcript: channel name in 600 ink, then mode and tag separated by middle dots; expiry countdown right-aligned.
 - **Motion:** when `animate` is set, every item takes `.arrive` with `--delay: 60ms + index * 70ms`, so a six-item room is fully on screen within about a second. Reduced motion zeroes both duration and delay.
 
+### Composer (`channel/compose.tsx`)
+The name field (asked once, at the first message), the box, the ink pill, and one hint line. Typing `@` opens the room above the box — never below, since the composer is already at the bottom of the window: a 12px-radius `panel` card with `shadow-soft`, at most 300px wide, holding roster rows (18px identity tile, name in 500, role badge, presence dot) with the active row on `panel-2`. Arrow keys move, Enter or Tab accepts, Escape closes, and `⌘↵` still sends whatever is open — the menu helps write the message, it never stands between the message and being sent. What it inserts is plain text: a spelling aid for names that run to several words and carry a dedupe suffix, not an addressing mechanism.
+
 ### Use-case carousel (`use-cases.tsx`)
 The landing page's product surface, in the hero under the create form. Six scenarios, each with the channel it would happen in. The picker row is a `.segmented` control holding a real radio group (three columns from `sm`, six from `lg`) — choosing one of six is a radio's own job, so the arrow keys come free and the `<legend>` is `sr-only` — with a `1 of 6` counter in 13px ink-3 and two 44px round `.btn-secondary` arrows pushed right, wrapping at either end. Below `sm` that whole right-hand group is hidden and the track becomes a `.segmented-rail`: one 44px row across the full width, the chosen label centred in it whenever the case changes and again after a rotation. Counter and arrows are pointer chrome — on a phone they would take a third of the row to say what the half-visible next label already says — so stepping there is a tap on the rail or a horizontal swipe on the panel (48px, and more horizontal than vertical, or it was the page being scrolled). The radios remain the control that keyboard and assistive technology see; the swipe is only a shortcut. The panel under it is three columns at `lg` (`0.8fr / 1.2fr / 212px`): the scenario's title (19px display 700) and body, the example transcript, and the room. Each column is divided by a `line-2` hairline that is a top border when stacked and a left border at `lg`. The transcript carries the 13px channel header (`name · standard · example`) and the panel holds a `25rem` minimum, so flipping through the six barely moves the page. Each example channel names real clients in its roster — Claude Code, Codex CLI, Cursor, Antigravity CLI — and the handoff case is the one that uses `idle` and `gone` presence, because that is what a handoff looks like.
 
diff --git a/app/components/channel/channel-view.tsx b/app/components/channel/channel-view.tsx
index 142549b..01e3152 100644
--- a/app/components/channel/channel-view.tsx
+++ b/app/components/channel/channel-view.tsx
@@ -5,12 +5,13 @@ import Link from "next/link";
 import { useEffect, useRef, useState } from "react";
 import { sileo, Toaster } from "sileo";
 import { identityPalette } from "@/lib/identity-color";
+import { quoteOf } from "@/lib/reply-quote";
 import { channelGone } from "@/lib/site";
 import mark from "../../icon.png";
 import { CreateChannelForm } from "../create-channel";
 import { ArrowRightIcon } from "../icons";
 import { Logo } from "../logo";
-import { Roster, Transcript, type TranscriptItem } from "../transcript";
+import { Roster, Transcript, type ReplyQuote, type TranscriptItem } from "../transcript";
 import { AddAgentDialog } from "./add-agent-dialog";
 import { announcementFor } from "./channel-events";
 import { ChannelAddButton, ChannelMenu, ChannelMenuButton, ChannelShareButton } from "./channel-menu";
@@ -46,6 +47,26 @@ function clockTime(ts: string): string {
   return new Date(ts).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
 }
 
+/**
+ * What a `reply_to` points at, as the line the transcript quotes.
+ *
+ * Resolved here rather than in the transcript because this is the surface that
+ * holds the channel: the page polls from seq 0, so every `seq` at or below the
+ * head is in `items`. References cannot dangle either — the item cap refuses
+ * new posts rather than trimming old ones — so the undefined below is for a
+ * build whose retention rules have changed, not for anything reachable today.
+ */
+function quoteFor(bySeq: Map<number, Item>, seq: number): ReplyQuote | undefined {
+  const answered = bySeq.get(seq);
+  if (!answered) return undefined;
+  if (answered.type === "system") return { seq, text: quoteOf(describe(answered)) };
+  return {
+    seq,
+    from: { name: answered.from.name, role: answered.from.role },
+    text: quoteOf(answered.text),
+  };
+}
+
 /**
  * The transcript, with anything still on its way to the channel on the end.
  *
@@ -54,6 +75,7 @@ function clockTime(ts: string): string {
  * React keeps the node and only the dimming changes.
  */
 function toTranscript(items: Item[], pending: PendingMessage[]): TranscriptItem[] {
+  const bySeq = new Map(items.map((item) => [item.seq, item]));
   const said: TranscriptItem[] = items.map((item) =>
     item.type === "system"
       ? { seq: item.seq, type: "system", text: describe(item) }
@@ -63,6 +85,7 @@ function toTranscript(items: Item[], pending: PendingMessage[]): TranscriptItem[
           from: { name: item.from.name, role: item.from.role },
           time: clockTime(item.ts),
           text: item.text,
+          ...(item.reply_to === undefined ? {} : { replyTo: quoteFor(bySeq, item.reply_to) }),
         },
   );
 
@@ -338,6 +361,7 @@ export function ChannelView({ channelId, host }: { channelId: string; host: stri
   // Joins alone do not start a conversation: the prompt stays put while agents
   // are still arriving, and steps aside once one of them says something.
   const started = pending.length > 0 || items.some((item) => item.type === "message");
+  const room = toRoster(participants, items, lastSeq, me?.id);
   const shareUrl = `${host}/c/${channelId}#${invite}`;
   const canClose = typeof window !== "undefined" && window.localStorage.getItem(adminKey(channelId)) !== null;
 
@@ -384,7 +408,7 @@ export function ChannelView({ channelId, host }: { channelId: string; host: stri
               {started ? (
                 <Transcript
                   items={toTranscript(items, pending)}
-                  room={toRoster(participants, items, lastSeq, me?.id)}
+                  room={room}
                   colorFor={colorFor}
                   unreadAfter={markerAt}
                 />
@@ -408,7 +432,7 @@ export function ChannelView({ channelId, host }: { channelId: string; host: stri
 
           <div className="shrink-0 border-t border-line">
             <div className="mx-auto w-full max-w-[92ch]">
-              <Compose joinedAs={me?.name ?? null} onSend={post} />
+              <Compose joinedAs={me?.name ?? null} onSend={post} participants={room} colorFor={colorFor} />
             </div>
           </div>
         </main>
@@ -424,7 +448,7 @@ export function ChannelView({ channelId, host }: { channelId: string; host: stri
             {participants.length === 0 ? (
               <p className="m-0 text-[13px] text-ink-3">Nobody has joined yet.</p>
             ) : (
-              <Roster participants={toRoster(participants, items, lastSeq, me?.id)} colorFor={colorFor} />
+              <Roster participants={room} colorFor={colorFor} />
             )}
           </section>
 
@@ -464,7 +488,7 @@ export function ChannelView({ channelId, host }: { channelId: string; host: stri
           {participants.length === 0 ? (
             <p className="m-0 text-[13px] text-ink-3">Nobody has joined yet.</p>
           ) : (
-            <Roster participants={toRoster(participants, items, lastSeq, me?.id)} colorFor={colorFor} />
+            <Roster participants={room} colorFor={colorFor} />
           )}
         </div>
         <div className="border-t border-line px-4 py-4">
diff --git a/app/components/channel/compose.test.ts b/app/components/channel/compose.test.ts
new file mode 100644
index 0000000..2d41c9d
--- /dev/null
+++ b/app/components/channel/compose.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import type { Participant } from "../transcript";
+import { suggest, tokenAt } from "./compose";
+
+/** The composer's `@` menu, without the composer: what it offers and when. */
+
+const room: Participant[] = [
+  { name: "David", role: "human", client: "", presence: "active" },
+  { name: "Windows agent", role: "agent", client: "codex-cli", presence: "idle" },
+  { name: "Linda's agent", role: "agent", client: "claude-code", presence: "gone" },
+];
+
+describe("tokenAt", () => {
+  it("finds the mention the caret is in", () => {
+    expect(tokenAt("ping @Dav", 9)).toEqual({ at: 5, query: "Dav" });
+  });
+
+  it("opens on a bare @", () => {
+    expect(tokenAt("@", 1)).toEqual({ at: 0, query: "" });
+  });
+
+  it("reads a name with a space in it as one query", () => {
+    expect(tokenAt("@Windows ag", 11)).toEqual({ at: 0, query: "Windows ag" });
+  });
+
+  it("finds nothing where there is no @ behind the caret", () => {
+    expect(tokenAt("ping David", 10)).toBeNull();
+  });
+
+  it("does not open inside an email address", () => {
+    expect(tokenAt("david@example", 13)).toBeNull();
+  });
+
+  it("stops at a newline, so an @ a paragraph up cannot hold the menu open", () => {
+    expect(tokenAt("@David\nthanks", 13)).toBeNull();
+  });
+
+  it("gives up once what was typed is too long to be a name", () => {
+    expect(tokenAt(`@${"x".repeat(80)}`, 81)).toBeNull();
+  });
+});
+
+describe("suggest", () => {
+  it("offers the whole room for a bare @", () => {
+    expect(suggest(room, "").map((p) => p.name)).toEqual(["David", "Windows agent", "Linda's agent"]);
+  });
+
+  it("puts a name that starts with the query ahead of one that merely contains it", () => {
+    expect(suggest(room, "lind").map((p) => p.name)).toEqual(["Linda's agent"]);
+    expect(suggest(room, "agent").map((p) => p.name)).toEqual(["Windows agent", "Linda's agent"]);
+  });
+
+  it("ignores case", () => {
+    expect(suggest(room, "WINDOWS").map((p) => p.name)).toEqual(["Windows agent"]);
+  });
+
+  it("offers someone who has gone, because naming them is a thing people mean to do", () => {
+    expect(suggest(room, "linda")[0].presence).toBe("gone");
+  });
+
+  it("offers nobody when the query matches nobody", () => {
+    expect(suggest(room, "zz")).toEqual([]);
+  });
+});
diff --git a/app/components/channel/compose.tsx b/app/components/channel/compose.tsx
index 396ee82..f0e9574 100644
--- a/app/components/channel/compose.tsx
+++ b/app/components/channel/compose.tsx
@@ -1,6 +1,15 @@
 "use client";
 
-import { useRef, useState } from "react";
+import { useEffect, useRef, useState } from "react";
+import { identityColor } from "@/lib/identity-color";
+import { seatingOf } from "@/lib/seating";
+import {
+  IdentityTile,
+  PresenceDot,
+  RoleBadge,
+  type ColorFor,
+  type Participant,
+} from "../transcript";
 
 /**
  * Humans speak here. The first message joins them to the channel, which is why
@@ -9,22 +18,112 @@ import { useRef, useState } from "react";
  * Sending empties the box immediately and leaves nothing waiting on the round
  * trip: the message is already in the transcript, dimmed, and the next one can
  * be typed while it lands.
+ *
+ * Typing `@` offers the room. What it inserts is plain text — the message is
+ * stored, sent and delivered exactly as if the name had been typed by hand —
+ * so this is a spelling aid, not an addressing mechanism. It exists because
+ * names in a channel can be several words long and are deduplicated with a
+ * suffix, and a mention only draws when it matches one exactly.
  */
+
+/** Past this many characters with no match, whatever was typed is not a name. */
+const MAX_QUERY = 48;
+
+/** The same boundary `lib/mentions.ts` uses: an `@` after a letter is an email address. */
+const WORD = /[\p{L}\p{N}_-]/u;
+
+export type MentionToken = { at: number; query: string };
+
+/**
+ * The `@…` the caret is sitting in, if it is sitting in one.
+ *
+ * Walks back from the caret to the nearest `@` that could open a mention,
+ * stopping at a newline: a name does not span lines, and without the stop a
+ * stray `@` three paragraphs up would keep the menu open forever.
+ */
+export function tokenAt(text: string, caret: number): MentionToken | null {
+  for (let index = caret - 1; index >= 0 && caret - index <= MAX_QUERY; index -= 1) {
+    const character = text[index];
+    if (character === "\n") return null;
+    if (character !== "@") continue;
+
+    const before = text[index - 1];
+    if (before !== undefined && WORD.test(before)) return null;
+    return { at: index, query: text.slice(index + 1, caret) };
+  }
+  return null;
+}
+
+/**
+ * Who the query offers, best first.
+ *
+ * A name that starts with what was typed comes before one that merely contains
+ * it, so "@da" offers "David" ahead of "Linda's agent". Everyone in the room is
+ * offered, whatever their presence: a mention of someone who has gone quiet is
+ * a thing a person means to write, and the row says so with its dot.
+ */
+export function suggest(participants: readonly Participant[], query: string): Participant[] {
+  const wanted = query.toLowerCase();
+  const opens: Participant[] = [];
+  const holds: Participant[] = [];
+  for (const participant of participants) {
+    const name = participant.name.toLowerCase();
+    if (name.startsWith(wanted)) opens.push(participant);
+    else if (wanted.length > 0 && name.includes(wanted)) holds.push(participant);
+  }
+  return [...opens, ...holds];
+}
+
 export function Compose({
   joinedAs,
   onSend,
+  participants = [],
+  colorFor = identityColor,
 }: {
   joinedAs: string | null;
   onSend: (text: string, name: string) => Promise<void>;
+  /** The room, for the `@` menu. Empty on a surface that has no roster. */
+  participants?: readonly Participant[];
+  colorFor?: ColorFor;
 }) {
   // The name is uncontrolled and read at send time: a browser autofilling it
   // does not always tell React, and a Send button that silently stays disabled
   // because of that is worse than asking for the name a moment later.
   const nameField = useRef<HTMLInputElement>(null);
+  const box = useRef<HTMLTextAreaElement>(null);
   const [text, setText] = useState("");
   const [failure, setFailure] = useState<string | null>(null);
+  const [token, setToken] = useState<MentionToken | null>(null);
+  const [active, setActive] = useState(0);
+  /** Where the caret goes once React has written an accepted mention into the box. */
+  const caretTo = useRef<number | null>(null);
 
   const ready = text.trim().length > 0;
+  const offered = token === null ? [] : suggest(participants, token.query);
+  const open = offered.length > 0;
+  const chosen = offered[Math.min(active, offered.length - 1)];
+
+  useEffect(() => {
+    if (caretTo.current === null) return;
+    box.current?.setSelectionRange(caretTo.current, caretTo.current);
+    caretTo.current = null;
+  });
+
+  /** Reads the token under the caret. Called after anything that can move it. */
+  function retrack(value: string, caret: number | null) {
+    setToken(caret === null ? null : tokenAt(value, caret));
+    setActive(0);
+  }
+
+  function accept(participant: Participant) {
+    if (!token) return;
+    const caret = box.current?.selectionStart ?? text.length;
+    // A trailing space, so the next word is not read as part of the name.
+    const inserted = `@${participant.name} `;
+    setText(`${text.slice(0, token.at)}${inserted}${text.slice(caret)}`);
+    caretTo.current = token.at + inserted.length;
+    setToken(null);
+  }
 
   async function send() {
     if (!ready) return;
@@ -40,6 +139,7 @@ export function Compose({
     const said = text.trim();
     setFailure(null);
     setText("");
+    setToken(null);
     try {
       await onSend(said, name);
     } catch (error) {
@@ -50,6 +150,8 @@ export function Compose({
     }
   }
 
+  const seatOf = seatingOf(participants);
+
   return (
     <div className="grid gap-2.5 px-4 py-3 lg:px-6">
       {joinedAs === null ? (
@@ -69,17 +171,89 @@ export function Compose({
         </div>
       ) : null}
 
-      <div className="grid gap-2">
+      <div className="relative grid gap-2">
         <label htmlFor="compose" className="sr-only">
           Message
         </label>
+        {/* Above the box rather than below it: the composer is already at the
+            bottom of the window, and a menu hanging off it would be off screen. */}
+        {open ? (
+          <ul
+            id="mention-menu"
+            role="listbox"
+            aria-label="Participants"
+            className="absolute bottom-full left-0 z-20 mb-1.5 max-h-56 w-full max-w-[300px] overflow-y-auto rounded-[12px] border border-line bg-panel p-1 shadow-soft"
+          >
+            {offered.map((participant, index) => (
+              <li
+                key={participant.name}
+                id={`mention-${index}`}
+                role="option"
+                aria-selected={participant === chosen}
+                // Mouse down, not click: the textarea would lose focus first,
+                // and with it the caret this has to write into.
+                onMouseDown={(event) => {
+                  event.preventDefault();
+                  accept(participant);
+                }}
+                onMouseEnter={() => setActive(index)}
+                className={`grid cursor-pointer grid-cols-[18px_1fr_auto] items-center gap-2 rounded-[8px] px-2 py-1.5 text-[13px] ${
+                  participant === chosen ? "bg-panel-2" : ""
+                }`}
+              >
+                <IdentityTile
+                  name={participant.name}
+                  colour={colorFor(participant.name, participant.role)}
+                  seat={seatOf(participant.name)}
+                />
+                <span className="min-w-0 truncate font-medium">{participant.name}</span>
+                <span className="flex shrink-0 items-center gap-2">
+                  <RoleBadge role={participant.role} />
+                  <PresenceDot presence={participant.presence} />
+                </span>
+              </li>
+            ))}
+          </ul>
+        ) : null}
         <textarea
           id="compose"
+          ref={box}
+          role="combobox"
+          aria-expanded={open}
+          aria-controls="mention-menu"
+          aria-autocomplete="list"
+          aria-activedescendant={open ? `mention-${Math.min(active, offered.length - 1)}` : undefined}
           className="input h-auto min-h-[52px] resize-y py-2.5 leading-relaxed"
           value={text}
-          onChange={(event) => setText(event.target.value)}
+          onChange={(event) => {
+            setText(event.target.value);
+            retrack(event.target.value, event.target.selectionStart);
+          }}
+          onSelect={(event) => retrack(event.currentTarget.value, event.currentTarget.selectionStart)}
+          onBlur={() => setToken(null)}
           onKeyDown={(event) => {
-            if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) void send();
+            // ⌘↵ sends whatever is open: the menu is an aid to writing the
+            // message, never a thing standing between it and being sent.
+            if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) {
+              void send();
+              return;
+            }
+            if (!open) return;
+            if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+              event.preventDefault();
+              const step = event.key === "ArrowDown" ? 1 : offered.length - 1;
+              setActive((current) => (Math.min(current, offered.length - 1) + step) % offered.length);
+              return;
+            }
+            if (event.key === "Enter" || event.key === "Tab") {
+              event.preventDefault();
+              accept(chosen);
+              return;
+            }
+            if (event.key === "Escape") {
+              event.preventDefault();
+              setToken(null);
+            }
           }}
           placeholder={joinedAs ? `Say something as ${joinedAs}…` : "Say something to the agents…"}
           maxLength={4_000}
@@ -90,7 +264,10 @@ export function Compose({
         <button type="button" className="btn btn-primary btn-sm" onClick={() => void send()} disabled={!ready}>
           Send
         </button>
-        <span className="text-xs text-ink-3">⌘↵ to send. Agents see it in their next poll.</span>
+        <span className="text-xs text-ink-3">
+          &#8984;&#8629; to send. Agents see it in their next poll.
+          {participants.length > 0 ? " Type @ to name someone." : ""}
+        </span>
       </div>
 
       {failure ? (
diff --git a/app/components/message-body.test.tsx b/app/components/message-body.test.tsx
new file mode 100644
index 0000000..33e0032
--- /dev/null
+++ b/app/components/message-body.test.tsx
@@ -0,0 +1,86 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { identityColor } from "@/lib/identity-color";
+import { MessageBody, type MentionTarget } from "./message-body";
+
+/**
+ * What comes out of the one component another agent's text reaches a browser
+ * through. Asserted as HTML rather than reasoned about: the mention highlight
+ * is a remark plugin rewriting the Markdown tree, and the thing worth proving
+ * is that it rewrites nothing it was not asked to.
+ */
+
+const room: MentionTarget[] = [
+  { name: "David", colour: identityColor("David", "human") },
+  { name: "Windows agent", colour: identityColor("Windows agent", "agent") },
+];
+
+function render(text: string, mentions: MentionTarget[] = room): string {
+  return renderToStaticMarkup(<MessageBody text={text} mentions={mentions} />);
+}
+
+/** The highlight, whatever colour it came out. */
+const MENTION = /<span class="rounded-\[5px\][^"]*"[^>]*>([^<]*)<\/span>/g;
+
+function highlighted(html: string): string[] {
+  return [...html.matchAll(MENTION)].map((match) => match[1]);
+}
+
+describe("mentions", () => {
+  it("highlights a name from the room, in that person's colour", () => {
+    const html = render("morning @David");
+    expect(highlighted(html)).toEqual(["@David"]);
+    expect(html).toContain("background-color:hsl(");
+  });
+
+  it("keeps the spelling the sender used", () => {
+    expect(highlighted(render("@david, @DAVID"))).toEqual(["@david", "@DAVID"]);
+  });
+
+  it("leaves a name nobody has as plain text", () => {
+    const html = render("@Nobody is here");
+    expect(highlighted(html)).toEqual([]);
+    expect(html).toContain("@Nobody is here");
+  });
+
+  it("leaves every name alone when the surface has no roster", () => {
+    expect(highlighted(render("@David", []))).toEqual([]);
+  });
+
+  it("does not touch a name inside inline code", () => {
+    const html = render("run `curl @David` now");
+    expect(highlighted(html)).toEqual([]);
+    expect(html).toContain("curl @David");
+  });
+
+  it("does not touch a name inside a fenced block", () => {
+    const html = render("```\nssh @David\n```");
+    expect(highlighted(html)).toEqual([]);
+    expect(html).toContain("<pre");
+  });
+
+  it("highlights inside the Markdown it finds the name in", () => {
+    const bold = render("**ask @David**");
+    expect(bold).toContain("<strong>");
+    expect(highlighted(bold)).toEqual(["@David"]);
+
+    const item = render("- @Windows agent to confirm");
+    expect(item).toContain("<li");
+    expect(highlighted(item)).toEqual(["@Windows agent"]);
+  });
+
+  it("still renders the Markdown around a mention", () => {
+    const html = render("# Status\n\n@David: `ok`\n\n- one\n- two");
+    expect(html).toContain("Status");
+    expect(html).toContain("<code");
+    expect(html).toContain("<ul");
+    expect(highlighted(html)).toEqual(["@David"]);
+  });
+
+  it("renders no HTML from the message, mention or not", () => {
+    const html = render('<img src=x onerror=alert(1)> @David <b>hi</b>');
+    expect(html).not.toContain("<img");
+    expect(html).not.toContain("<b>hi");
+    expect(highlighted(html)).toEqual(["@David"]);
+  });
+});
diff --git a/app/components/message-body.tsx b/app/components/message-body.tsx
index 3904469..00e8940 100644
--- a/app/components/message-body.tsx
+++ b/app/components/message-body.tsx
@@ -3,6 +3,8 @@
 import { useState, type ReactNode } from "react";
 import Markdown from "react-markdown";
 import remarkGfm from "remark-gfm";
+import type { IdentityColor } from "@/lib/identity-color";
+import { remarkMentions } from "@/lib/mentions";
 
 /**
  * A message body, rendered as Markdown (PRODUCT section 6.2).
@@ -14,6 +16,11 @@ import remarkGfm from "remark-gfm";
  *
  * Long messages collapse. An agent pasting a file should not push the rest of
  * the conversation off the screen, and the reader decides when to look.
+ *
+ * `@name` is highlighted where the name belongs to someone in this channel,
+ * and left as plain text where it does not (lib/mentions.ts). It is a
+ * rendering of ordinary message text: nothing was stored to make it, and
+ * nothing about delivery changes because of it.
  */
 
 /** Past this, a message is folded until asked for. Roughly fifteen lines of body text. */
@@ -79,10 +86,74 @@ const components = {
   hr: () => <hr className="my-3 border-0 border-t border-line-2" />,
 };
 
-export function MessageBody({ text }: { text: string }) {
+/**
+ * Who `@name` may resolve to, with their colour already looked up.
+ *
+ * Resolved by the caller rather than through a `colorFor` passed down: this is
+ * a client component, the transcript that renders it is not everywhere, and a
+ * function cannot cross that boundary. Plain data can.
+ */
+export type MentionTarget = { name: string; colour: IdentityColor };
+
+/**
+ * A resolved mention, in the hue its subject wears everywhere else.
+ *
+ * The Identity-In-The-Tile Rule, extended to the one other place a
+ * participant's name is drawn as an object rather than as prose: the same
+ * person is the same colour in the roster, on their messages, and here. Five
+ * pixels of radius rather than a pill, so it sits in the same register as
+ * inline code — both are a token inside a sentence, not a badge beside one.
+ *
+ * Three pixels of side padding and no more. A mention is usually followed
+ * straight away by a comma or a full stop, and anything wider leaves the
+ * punctuation floating a space away from the name it belongs to.
+ */
+function Mention({ label, colour }: { label: string; colour: IdentityColor }) {
+  return (
+    <span
+      className="rounded-[5px] px-[3px] py-px font-semibold"
+      style={{ backgroundColor: colour.fill, color: colour.ink }}
+    >
+      {label}
+    </span>
+  );
+}
+
+/** The text of a node the mention plugin built, which is always one string child. */
+function labelOf(children: ReactNode): string | null {
+  if (typeof children === "string") return children;
+  if (Array.isArray(children) && children.length === 1 && typeof children[0] === "string") return children[0];
+  return null;
+}
+
+export function MessageBody({
+  text,
+  mentions = [],
+}: {
+  text: string;
+  /** The room. Empty leaves every `@name` as plain text, which is what a surface with no roster wants. */
+  mentions?: readonly MentionTarget[];
+}) {
   const [expanded, setExpanded] = useState(false);
   const long = text.length > LONG_MESSAGE;
 
+  // Rebuilt per render rather than memoised: the plugin closes over the roster,
+  // which changes whenever anyone's presence does, and a stale one would
+  // silently stop recognising whoever joined last.
+  const named = new Map(mentions.map((target) => [target.name.toLowerCase(), target]));
+  const plugins = named.size > 0 ? [remarkGfm, remarkMentions([...mentions.map((m) => m.name)])] : [remarkGfm];
+  const rendered = {
+    ...components,
+    // The only span in this tree: raw HTML is not enabled, so nothing else can
+    // produce one. See lib/mentions.ts for where it comes from.
+    span: ({ className, children }: { className?: string; children?: ReactNode }) => {
+      const label = className === "mention" ? labelOf(children) : null;
+      const target = label === null ? undefined : named.get(label.slice(1).toLowerCase());
+      if (label === null || !target) return <span className={className}>{children}</span>;
+      return <Mention label={label} colour={target.colour} />;
+    },
+  };
+
   return (
     <div className="min-w-0">
       <div
@@ -90,7 +161,7 @@ export function MessageBody({ text }: { text: string }) {
           long && !expanded ? "relative max-h-52 overflow-hidden [mask-image:linear-gradient(to_bottom,black_65%,transparent)]" : ""
         }`}
       >
-        <Markdown remarkPlugins={[remarkGfm]} components={components}>
+        <Markdown remarkPlugins={plugins} components={rendered}>
           {text}
         </Markdown>
       </div>
diff --git a/app/components/transcript.tsx b/app/components/transcript.tsx
index fa3082e..c4ff663 100644
--- a/app/components/transcript.tsx
+++ b/app/components/transcript.tsx
@@ -9,6 +9,21 @@ import { MessageBody } from "./message-body";
 export type Role = "agent" | "human";
 export type Presence = "active" | "idle" | "gone";
 
+/**
+ * The item a message answers, already resolved and already cut to a line.
+ *
+ * The transcript is handed the quote rather than the `reply_to` seq, because
+ * finding the referenced item is the job of whoever holds the channel — a
+ * surface showing an example conversation has no channel to look in.
+ */
+export type ReplyQuote = {
+  seq: number;
+  /** Absent when the reply points at a system event, which has no author. */
+  from?: { name: string; role: Role };
+  /** One line. Cut by `quoteOf` before it gets here (lib/reply-quote.ts). */
+  text: string;
+};
+
 export type TranscriptItem =
   | {
       /** Channel sequence number. Absent for illustrative transcripts. */
@@ -17,6 +32,8 @@ export type TranscriptItem =
       from: { name: string; role: Role };
       time: string;
       text: string;
+      /** What this answers, when the sender set `reply_to`. */
+      replyTo?: ReplyQuote;
       /** Said here but not yet handed back by the channel. Drawn dimmed until it is. */
       pending?: boolean;
     }
@@ -76,7 +93,7 @@ export type ColorFor = (name: string, role: Role) => IdentityColor;
  * does not. A client with no mark is always the identity tile, which is what
  * every tile was before any of this.
  */
-function IdentityTile({
+export function IdentityTile({
   name,
   colour,
   seat,
@@ -119,6 +136,33 @@ function IdentityTile({
   );
 }
 
+/**
+ * What a message answers, above the message that answers it.
+ *
+ * One line, quoted, and nothing more: a rendered quote keeps one stream and
+ * one sequence, where a thread view would split the transcript into many and
+ * fight both the resume-from-`last_seq` contract and the premise that a
+ * channel is one readable conversation.
+ *
+ * Deliberately not a link to the item it quotes. The channel page carries its
+ * invite in the URL fragment, so anything that sets `location.hash` — an
+ * anchor included — throws the invite away; a jump would have to be a click
+ * handler, and that would make this whole file a client component for the sake
+ * of a scroll.
+ */
+function ReplyQuoteLine({ quote }: { quote: ReplyQuote }) {
+  return (
+    <div className="mb-1 flex min-w-0 items-baseline gap-1.5 border-l-2 border-line-2 pl-2 text-[12.5px] text-ink-3">
+      <span aria-hidden className="shrink-0">
+        &#x21B3;
+      </span>
+      <span className="sr-only">Replying to</span>
+      {quote.from ? <b className="shrink-0 font-semibold">{quote.from.name}</b> : null}
+      <span className="truncate">{quote.text}</span>
+    </div>
+  );
+}
+
 /** The line you had read up to. Drawn above the first item past `unreadAfter`. */
 function UnreadLine() {
   return (
@@ -141,13 +185,20 @@ export function Transcript({
   /** Seq the reader had reached. The divider goes before the first item past it. */
   unreadAfter?: number | null;
   /**
-   * Who is in the room. A transcript knows only names, and whether a tile may
-   * be its client's mark is a question about the whole room, so a surface that
-   * has a roster passes it. Without one every tile is the plain identity tile.
+   * Who is in the room. Two things are questions about the whole room rather
+   * than about one item — whether a tile may be its client's mark, and whether
+   * an `@name` is anybody — so a surface that has a roster passes it. Without
+   * one every tile is the plain identity tile and every `@name` is prose.
    */
   room?: readonly Participant[];
 }) {
   const seatOf = seatingOf(room ?? []);
+  // Colours resolved once, here: `MessageBody` is a client component and this
+  // one is not everywhere, so what crosses that boundary has to be data.
+  const mentionable = (room ?? []).map((person) => ({
+    name: person.name,
+    colour: colorFor(person.name, person.role),
+  }));
   const firstUnread =
     unreadAfter === null ? undefined : items.find((item) => item.seq !== undefined && item.seq > unreadAfter)?.seq;
   return (
@@ -195,7 +246,8 @@ export function Transcript({
                   <time className="text-xs text-ink-3">{item.time}</time>
                 )}
               </div>
-              <MessageBody text={item.text} />
+              {item.replyTo ? <ReplyQuoteLine quote={item.replyTo} /> : null}
+              <MessageBody text={item.text} mentions={mentionable} />
             </div>
           </li>
           </Fragment>
diff --git a/docs/IDEAS.md b/docs/IDEAS.md
index c3a3b57..3294c61 100644
--- a/docs/IDEAS.md
+++ b/docs/IDEAS.md
@@ -69,6 +69,8 @@ Smallest useful version: no new endpoint. Document that an agent may call create
 
 ## 4. Mentions
 
+**The smallest useful version below shipped (#64).** `@name` is autocompleted in the composer, highlighted in the transcript where it matches someone in the room, and stored as ordinary text; nothing resolves it server-side and poll is unchanged. Everything under "what it would break or require" is still open, and is what a structured field would have to answer.
+
 A message names the participant it is for — an agent or a human — so the addressee knows it is being spoken to and everyone else knows they are not. Nothing carries an addressee today: every message goes to the whole channel, and each participant works out from the prose whether it concerns them.
 
 Why it might be worth doing:
@@ -91,7 +93,9 @@ Smallest useful version: `@name` as a display-only affordance — autocompleted
 
 ## 5. Replies
 
-A message points at the earlier message it answers, by `seq`. Half-built already: `POST /messages` accepts `reply_to`, rejects a value ahead of the channel, and stores it on the item — but nothing reads it. The browser transcript does not render it, and the join prompt never tells an agent to set one.
+**The smallest useful version below shipped (#63).** The browser renders `reply_to` as one quoted line and the join prompt says when not to set one. No threading, no filtering, no API change.
+
+A message points at the earlier message it answers, by `seq`. `POST /messages` accepts `reply_to`, rejects a value ahead of the channel, and stores it on the item. For a long time nothing read it.
 
 Why it might be worth doing:
 
diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md
index a633bbc..c4d64c5 100644
--- a/docs/PRODUCT.md
+++ b/docs/PRODUCT.md
@@ -69,9 +69,9 @@ Wave provides the wire. It does not provide orchestration, shared filesystems, o
 Sections:
 
 - **Prompt box.** The full join prompt with a **copy** button and an editable **Agent name** field above it. Editing the field rewrites the name line inside the prompt. Default value: `<MY NAME>'s agent` — a blank to fill, which survives being pasted into an agent unedited. The prompt also carries an inline comment telling a recipient who never visits the site how to edit that line themselves.
-- **Transcript.** Live stream of messages and events, newest at the bottom, sender name and role badge on each item. Human and agent messages are visually distinct. Events render as muted one-liners ("Windows agent joined").
+- **Transcript.** Live stream of messages and events, newest at the bottom, sender name and role badge on each item. Human and agent messages are visually distinct. Events render as muted one-liners ("Windows agent joined"). A message that carries `reply_to` shows one quoted line of what it answers above it, truncated; a message naming someone in the room with `@name` shows that name highlighted in their colour. Both are drawn from what was already stored: a reply is the `reply_to` field the API has always accepted, and a mention is ordinary message text.
 - **Participants.** Roster with presence: active, idle, gone.
-- **Compose.** Humans can post into the channel. Posting joins the human as a participant with role `human` under a name they choose.
+- **Compose.** Humans can post into the channel. Posting joins the human as a participant with role `human` under a name they choose. Typing `@` offers the roster and inserts the name as plain text — names are unique within a channel and may run to several words, so the spelling is worth helping with.
 - **Controls.** Share link, expiry countdown, **Close channel** (creator only). Closing purges all data immediately.
 - **Export.** The transcript as Markdown or JSON, built in the browser from what the page already holds. No request is made, which is what lets it work in `e2ee` mode, where the server has only ciphertext.
 
@@ -247,6 +247,10 @@ EOS
      have several sessions open, and the title is what tells them which one is in this room.
    - Say what you are about to do before a long silence. A peer cannot tell a thinking agent from
      a stopped one, and the channel has no way to ask.
+   - Set "reply_to" only when what you are answering is no longer the last thing said, and the
+     transcript would otherwise not show which message you mean. On every message it is a wall of
+     quotes. To send one, add --argjson r <that seq> to the jq in step 3 and ask it for
+     '{text: ., client_id: $c, reply_to: $r}'.
 
 6. Finish: when the task is complete, say goodbye from a new file — reuse msg.txt and you sign off
    by re-posting your introduction — then leave:
@@ -394,6 +398,8 @@ Request: `{ "text": string(1..64 KB), "kind"?: "message" | "done", "reply_to"?:
 
 `client_id` gives idempotency for retries within 5 minutes.
 
+`reply_to` is the seq this message answers. It is refused if it is ahead of the channel, and otherwise stored and handed back on the item. The browser renders it as one quoted line; nothing on the server reads it, and nothing about delivery changes because of it. There is no addressee field: a message that names someone does so in its own text.
+
 Response: `{ "seq", "ts" }`
 
 
diff --git a/lib/join-prompt.ts b/lib/join-prompt.ts
index bcba222..341588a 100644
--- a/lib/join-prompt.ts
+++ b/lib/join-prompt.ts
@@ -129,6 +129,10 @@ EOS
      have several sessions open, and the title is what tells them which one is in this room.
    - Say what you are about to do before a long silence. A peer cannot tell a thinking agent from
      a stopped one, and the channel has no way to ask.
+   - Set "reply_to" only when what you are answering is no longer the last thing said, and the
+     transcript would otherwise not show which message you mean. On every message it is a wall of
+     quotes. To send one, add --argjson r <that seq> to the jq in step 3 and ask it for
+     '{text: ., client_id: $c, reply_to: $r}'.
 
 6. Finish: when the task is complete, say goodbye from a new file — reuse msg.txt and you sign off
    by re-posting your introduction — then leave:
diff --git a/lib/mentions.test.ts b/lib/mentions.test.ts
new file mode 100644
index 0000000..23d379f
--- /dev/null
+++ b/lib/mentions.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import { findMentions } from './mentions'
+
+const room = ['David', "David's agent", 'Windows agent']
+
+/** Just the names, in order, which is what every assertion here is actually about. */
+function named(text: string, names: readonly string[] = room): string[] {
+  return findMentions(text, names).map((mention) => mention.name)
+}
+
+describe('findMentions', () => {
+  it('finds a name from the room', () => {
+    expect(findMentions('ping @David please', room)).toEqual([{ index: 5, length: 6, name: 'David' }])
+  })
+
+  it('finds a name with spaces in it, which is most of why the roster is the dictionary', () => {
+    expect(named('over to @Windows agent now')).toEqual(['Windows agent'])
+  })
+
+  it('takes the longest name that matches, not the first one that starts', () => {
+    expect(named("@David's agent, can you look")).toEqual(["David's agent"])
+    // And the shorter one still wins where the longer one does not fit.
+    expect(named('@David, can you look')).toEqual(['David'])
+  })
+
+  it('leaves a name nobody in the room has as plain text', () => {
+    expect(named('@Nobody @david-sling @')).toEqual([])
+  })
+
+  it('is case-insensitive, and reports the roster spelling', () => {
+    expect(named('@david and @WINDOWS AGENT')).toEqual(['David', 'Windows agent'])
+  })
+
+  it('will not read an email address as a mention', () => {
+    expect(named('david@David.example and x@Windows agent')).toEqual([])
+  })
+
+  it('will not match a name that the text runs past', () => {
+    expect(named('@Davidson shipped it')).toEqual([])
+    // A non-word character is not running past it.
+    expect(named('@David, @David. @David!')).toEqual(['David', 'David', 'David'])
+  })
+
+  it('finds several without overlapping them', () => {
+    const found = findMentions('@David and @Windows agent', room)
+    expect(found.map((m) => m.index)).toEqual([0, 11])
+    expect(found[0].index + found[0].length).toBeLessThanOrEqual(found[1].index)
+  })
+
+  it('finds nothing in an empty room', () => {
+    expect(named('@David', [])).toEqual([])
+  })
+})
diff --git a/lib/mentions.ts b/lib/mentions.ts
new file mode 100644
index 0000000..714370f
--- /dev/null
+++ b/lib/mentions.ts
@@ -0,0 +1,129 @@
+/**
+ * `@name` in a message body (docs/IDEAS.md section 4).
+ *
+ * Display only. A mention is ordinary text in the message: nothing resolves it
+ * server-side, nothing is stored beside it, and poll returns the same items to
+ * everyone whether they are named or not. Addressing is not filtering — that
+ * line is what keeps `seq` meaning the same thing to every reader.
+ *
+ * The roster is the dictionary. A mention is recognised only when what follows
+ * the `@` is the name of someone in this channel, which is what makes names
+ * with spaces work — "@David's agent" is one mention, not a mention of "David"
+ * followed by prose — and what degrades a mention of nobody to plain text
+ * without a rule of its own. Names are already unique within a channel
+ * (`dedupeName`), so no namespace had to be invented for this.
+ */
+
+export type MentionMatch = {
+  /** Index of the `@` in the text. */
+  index: number
+  /** Characters consumed, `@` included. */
+  length: number
+  /** The roster name that matched, in the roster's spelling. */
+  name: string
+}
+
+/**
+ * What may not sit either side of a mention. Unicode-aware, because names are:
+ * an `@` after a letter is an email address, and a letter after the name means
+ * the reader typed past whoever matched. The hyphen counts as a letter here —
+ * "@david-sling" is one handle and not a mention of David with a tail.
+ */
+const WORD = /[\p{L}\p{N}_-]/u
+
+function matchesAt(text: string, at: number, name: string): boolean {
+  if (text.slice(at, at + name.length).toLowerCase() !== name.toLowerCase()) return false
+  const after = text[at + name.length]
+  return after === undefined || !WORD.test(after)
+}
+
+/**
+ * Every mention in a string, left to right and never overlapping.
+ *
+ * Longest name first, so a room holding both "David" and "David's agent" reads
+ * "@David's agent" as the longer of the two rather than as the shorter one
+ * with a possessive stuck to it.
+ */
+export function findMentions(text: string, names: readonly string[]): MentionMatch[] {
+  const ordered = [...new Set(names.filter((name) => name.length > 0))].sort((a, b) => b.length - a.length)
+  if (ordered.length === 0) return []
+
+  const found: MentionMatch[] = []
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] !== '@') continue
+    const before = text[index - 1]
+    if (before !== undefined && WORD.test(before)) continue
+
+    const name = ordered.find((candidate) => matchesAt(text, index + 1, candidate))
+    if (!name) continue
+
+    found.push({ index, length: name.length + 1, name })
+    index += name.length
+  }
+  return found
+}
+
+/**
+ * The parts of a mdast tree a mention may appear in. Only `text` nodes are
+ * visited, which is the whole of why code is left alone: `inlineCode` and
+ * `code` carry a `value` and no children, so an `@name` inside backticks or a
+ * fenced block is never reached.
+ */
+type MarkdownNode = {
+  type: string
+  value?: string
+  children?: MarkdownNode[]
+  data?: Record<string, unknown>
+}
+
+/**
+ * A remark plugin that splits mentions out of the text so they can be drawn.
+ *
+ * The mention becomes a `span.mention` carrying the author's own spelling —
+ * `@david` stays `@david` rather than being corrected to the roster's case.
+ * The message is the record; the highlight is the only thing saying it
+ * resolved.
+ */
+export function remarkMentions(names: readonly string[]) {
+  return function attach() {
+    return function transform(tree: MarkdownNode): void {
+      if (names.length > 0) divide(tree, names)
+    }
+  }
+}
+
+function divide(node: MarkdownNode, names: readonly string[]): void {
+  if (!node.children) return
+
+  const rebuilt: MarkdownNode[] = []
+  for (const child of node.children) {
+    if (child.type !== 'text' || typeof child.value !== 'string') {
+      divide(child, names)
+      rebuilt.push(child)
+      continue
+    }
+    rebuilt.push(...split(child.value, names))
+  }
+  node.children = rebuilt
+}
+
+function split(text: string, names: readonly string[]): MarkdownNode[] {
+  const found = findMentions(text, names)
+  if (found.length === 0) return [{ type: 'text', value: text }]
+
+  const parts: MarkdownNode[] = []
+  let at = 0
+  for (const mention of found) {
+    if (mention.index > at) parts.push({ type: 'text', value: text.slice(at, mention.index) })
+    parts.push({
+      type: 'mention',
+      // `hName` and `hProperties` are how mdast-util-to-hast is told what an
+      // unknown node becomes, so nothing here has to know about rehype.
+      data: { hName: 'span', hProperties: { className: ['mention'] } },
+      children: [{ type: 'text', value: text.slice(mention.index, mention.index + mention.length) }],
+    })
+    at = mention.index + mention.length
+  }
+  if (at < text.length) parts.push({ type: 'text', value: text.slice(at) })
+  return parts
+}
diff --git a/lib/reply-quote.test.ts b/lib/reply-quote.test.ts
new file mode 100644
index 0000000..08755d1
--- /dev/null
+++ b/lib/reply-quote.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { QUOTE_LIMIT, quoteOf } from './reply-quote'
+
+describe('quoteOf', () => {
+  it('leaves a short message alone', () => {
+    expect(quoteOf('Build passes on Windows.')).toBe('Build passes on Windows.')
+  })
+
+  it('flattens a message to one line', () => {
+    expect(quoteOf('# Status\n\n- one\n- two\n')).toBe('# Status - one - two')
+  })
+
+  it('cuts a long message at a word', () => {
+    const quote = quoteOf('word '.repeat(80))
+    expect(quote.length).toBeLessThanOrEqual(QUOTE_LIMIT + 1)
+    expect(quote.endsWith('word…')).toBe(true)
+  })
+
+  it('cuts mid-token rather than back to nothing when there is no word to cut at', () => {
+    const quote = quoteOf(`https://example.com/${'a'.repeat(400)}`)
+    expect(quote).toHaveLength(QUOTE_LIMIT + 1)
+    expect(quote.endsWith('…')).toBe(true)
+  })
+
+  it('takes a message far over the cap down to one line', () => {
+    expect(quoteOf('x'.repeat(64 * 1024)).length).toBe(QUOTE_LIMIT + 1)
+  })
+})
diff --git a/lib/reply-quote.ts b/lib/reply-quote.ts
new file mode 100644
index 0000000..f2c0d47
--- /dev/null
+++ b/lib/reply-quote.ts
@@ -0,0 +1,29 @@
+/**
+ * The one line of an earlier item that a reply quotes (docs/IDEAS.md section 5).
+ *
+ * The thing being quoted may be a 64 KB message, a fenced code block, or a
+ * system event, so the quote is cut to a sentence's worth of plain text before
+ * it reaches the DOM rather than being clipped there with CSS. Two reasons for
+ * doing it here: the browser should not hold a second copy of every quoted
+ * message, and Markdown flattened by an ellipsis is prose, not a half-open
+ * code fence.
+ */
+
+/** Roughly one line at the transcript's width, and short enough to stay one. */
+export const QUOTE_LIMIT = 140
+
+/**
+ * Collapses an item's text to a single line, cut at a word where one is near
+ * the end. Returns the text unchanged when it already fits.
+ */
+export function quoteOf(text: string, limit: number = QUOTE_LIMIT): string {
+  const line = text.replace(/\s+/g, ' ').trim()
+  if (line.length <= limit) return line
+
+  const cut = line.slice(0, limit)
+  const space = cut.lastIndexOf(' ')
+  // Only if the last word is a word rather than most of the quote: a message
+  // with no spaces in its first 140 characters is a URL or a token, and
+  // cutting it back to nothing to avoid breaking it helps no one.
+  return `${(space > limit * 0.6 ? cut.slice(0, space) : cut).trimEnd()}…`
+}
diff --git a/vitest.config.mts b/vitest.config.mts
index 3007e97..6b5d179 100644
--- a/vitest.config.mts
+++ b/vitest.config.mts
@@ -4,7 +4,10 @@ export default defineConfig({
   resolve: { tsconfigPaths: true },
   test: {
     environment: 'node',
-    include: ['lib/**/*.test.ts', 'app/**/*.test.ts', 'tests/**/*.test.ts'],
+    // `.tsx` as well, for the components whose whole job is what they render:
+    // a message body is the one place another agent's text reaches a browser,
+    // so what comes out of it is worth asserting rather than reasoning about.
+    include: ['lib/**/*.test.ts?(x)', 'app/**/*.test.ts?(x)', 'tests/**/*.test.ts?(x)'],
     // The end-to-end run needs a live instance and real waiting. It has its own
     // config and its own command; `npm test` stays hermetic.
     exclude: ['**/node_modules/**', 'tests/e2e/**', 'tests/integration/**'],

From d5724662cd08e4bd19994e7154a05f1e4aa179e4 Mon Sep 17 00:00:00 2001
From: David S D <me@davidsling.in>
Date: Wed, 16 Sep 2026 23:56:00 +0530
Subject: [PATCH 2/4] Let a human answer a message, not only read one that was
 answered
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replies shipped render-only: the transcript drew reply_to and agents set it.
That left the one participant who is actually looking at the transcript as
the only one who could not point at a message in it, which is the wrong way
round — a human watching four agents is exactly who needs to say which of
them they mean.

Reply on a row sets the target, the composer shows the quote it will send
until it goes or is cancelled, and the draft carries that quote while it is
in flight rather than growing one on arrival. Cleared on success only: a
failed post hands its text back, and it would otherwise hand back a reply
that no longer knew what it answered.

The control is its own client component reading a context, rather than an
onReply prop. A prop would have forced "use client" onto the transcript,
which is a server component on six marketing pages, and shipped it, its
seating and its marks into bundles that have no composer to reply into.
Outside a provider it renders nothing, which is the right answer for an
example conversation, and there is a test on the nothing.

Refs #63

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 DESIGN.md                               |  3 +-
 app/components/channel/channel-view.tsx | 35 ++++++++++++++----
 app/components/channel/compose.tsx      | 45 +++++++++++++++++++++--
 app/components/channel/use-channel.ts   | 14 ++++++--
 app/components/reply-action.test.tsx    | 36 +++++++++++++++++++
 app/components/reply-action.tsx         | 47 +++++++++++++++++++++++++
 app/components/transcript.tsx           |  2 ++
 docs/IDEAS.md                           |  2 +-
 docs/PRODUCT.md                         |  2 +-
 9 files changed, 171 insertions(+), 15 deletions(-)
 create mode 100644 app/components/reply-action.test.tsx
 create mode 100644 app/components/reply-action.tsx

diff --git a/DESIGN.md b/DESIGN.md
index fe32479..840268e 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -363,6 +363,7 @@ The signature component. Rendering conventions:
 - **Role badge:** pill, `1px 7px`, 12px 600, tracking 0.02em; `sky-soft`/`sky-ink` for `agent`, `peach-soft`/`peach-ink` for `human`. The literal role word is the label.
 - **Message body:** rendered as Markdown (`app/components/message-body.tsx`), because agents write it whether or not they are asked to. Inline code keeps the 12.5px mono, `panel-2` fill, 1px `line-2` border, 5px radius; fenced blocks take the same tone at 12px radius and scroll horizontally. Headings inside a message drop to body weight one size up — a message is not a page. Raw HTML is never rendered; message text is the one untrusted thing that reaches the browser.
 - **Reply quote:** when a message carries `reply_to`, a single 12.5px ink-3 line sits between the header and the body, behind a 2px `line-2` left rule and a `↳`: the answered participant's name in 600, then one line of what they said, truncated. The quoted text is flattened and cut to 140 characters before it is drawn (`lib/reply-quote.ts`), not clipped with CSS — the thing being quoted may be 64 KB of Markdown, and a half-open code fence is not a quote. A reply to a system event drops the name and quotes the event's own sentence. It is not a link: the channel page keeps its invite in the URL fragment, so anything that sets `location.hash` throws the invite away.
+- **Reply control:** a 12px 600 ink-3 "Reply" at the end of the header line, drawn only on `:hover` of the row and on `:focus-visible` of itself — the second half is what keeps it reachable by keyboard and on a phone. It stays in the tab order in both states, so only paint changes and nothing reflows. Its accessible name carries the author ("Reply to Windows agent"), since a transcript otherwise offers a column of identical buttons. It is a client component of its own (`reply-action.tsx`) reading a context, so the transcript stays a server component: on a surface with no composer — every `/uses` page — it renders nothing at all.
 - **Mention:** `@name` matching someone in the room is drawn in that participant's identity colour — their tile fill behind, their tile ink in front — at 600 weight, 5px radius, 3px of side padding. A name that matches nobody stays plain text, and so does any `@name` inside code. The sender's own spelling is kept; the highlight is the only thing saying it resolved.
 - **Long messages fold.** Past about 900 characters the body clamps to `max-h-52` under a linear-gradient mask and offers "Show more" with the character count. The threshold is on the text, not on measured height, so there is no layout read and the behaviour is the same on every screen.
 - **System event:** a single 12.5px ink-3 line centred between two `line` hairlines (`.hairline-between`). No avatar, no badge, no time.
@@ -372,7 +373,7 @@ The signature component. Rendering conventions:
 - **Motion:** when `animate` is set, every item takes `.arrive` with `--delay: 60ms + index * 70ms`, so a six-item room is fully on screen within about a second. Reduced motion zeroes both duration and delay.
 
 ### Composer (`channel/compose.tsx`)
-The name field (asked once, at the first message), the box, the ink pill, and one hint line. Typing `@` opens the room above the box — never below, since the composer is already at the bottom of the window: a 12px-radius `panel` card with `shadow-soft`, at most 300px wide, holding roster rows (18px identity tile, name in 500, role badge, presence dot) with the active row on `panel-2`. Arrow keys move, Enter or Tab accepts, Escape closes, and `⌘↵` still sends whatever is open — the menu helps write the message, it never stands between the message and being sent. What it inserts is plain text: a spelling aid for names that run to several words and carry a dedupe suffix, not an addressing mechanism.
+The name field (asked once, at the first message), the box, the ink pill, and one hint line. Replying puts the transcript's own quote line above the box — same `↳`, same `line-2` left rule, same 12.5px ink-3 — with a Cancel at the end of it, and the placeholder becomes "Reply to <name>…". Escape cancels the reply, but only once the mention menu has closed: the menu has first claim on the key. Typing `@` opens the room above the box — never below, since the composer is already at the bottom of the window: a 12px-radius `panel` card with `shadow-soft`, at most 300px wide, holding roster rows (18px identity tile, name in 500, role badge, presence dot) with the active row on `panel-2`. Arrow keys move, Enter or Tab accepts, Escape closes, and `⌘↵` still sends whatever is open — the menu helps write the message, it never stands between the message and being sent. What it inserts is plain text: a spelling aid for names that run to several words and carry a dedupe suffix, not an addressing mechanism.
 
 ### Use-case carousel (`use-cases.tsx`)
 The landing page's product surface, in the hero under the create form. Six scenarios, each with the channel it would happen in. The picker row is a `.segmented` control holding a real radio group (three columns from `sm`, six from `lg`) — choosing one of six is a radio's own job, so the arrow keys come free and the `<legend>` is `sr-only` — with a `1 of 6` counter in 13px ink-3 and two 44px round `.btn-secondary` arrows pushed right, wrapping at either end. Below `sm` that whole right-hand group is hidden and the track becomes a `.segmented-rail`: one 44px row across the full width, the chosen label centred in it whenever the case changes and again after a rotation. Counter and arrows are pointer chrome — on a phone they would take a third of the row to say what the half-visible next label already says — so stepping there is a tap on the rail or a horizontal swipe on the panel (48px, and more horizontal than vertical, or it was the page being scrolled). The radios remain the control that keyboard and assistive technology see; the swipe is only a shortcut. The panel under it is three columns at `lg` (`0.8fr / 1.2fr / 212px`): the scenario's title (19px display 700) and body, the example transcript, and the room. Each column is divided by a `line-2` hairline that is a top border when stacked and a left border at `lg`. The transcript carries the 13px channel header (`name · standard · example`) and the panel holds a `25rem` minimum, so flipping through the six barely moves the page. Each example channel names real clients in its roster — Claude Code, Codex CLI, Cursor, Antigravity CLI — and the handoff case is the one that uses `idle` and `gone` presence, because that is what a handoff looks like.
diff --git a/app/components/channel/channel-view.tsx b/app/components/channel/channel-view.tsx
index 01e3152..75af3d7 100644
--- a/app/components/channel/channel-view.tsx
+++ b/app/components/channel/channel-view.tsx
@@ -11,6 +11,7 @@ import mark from "../../icon.png";
 import { CreateChannelForm } from "../create-channel";
 import { ArrowRightIcon } from "../icons";
 import { Logo } from "../logo";
+import { ReplyProvider } from "../reply-action";
 import { Roster, Transcript, type ReplyQuote, type TranscriptItem } from "../transcript";
 import { AddAgentDialog } from "./add-agent-dialog";
 import { announcementFor } from "./channel-events";
@@ -95,6 +96,7 @@ function toTranscript(items: Item[], pending: PendingMessage[]): TranscriptItem[
       from: { name: draft.name, role: "human" },
       time: clockTime(draft.ts),
       text: draft.text,
+      ...(draft.replyTo === undefined ? {} : { replyTo: quoteFor(bySeq, draft.replyTo) }),
       pending: true,
     });
   }
@@ -297,6 +299,8 @@ export function ChannelView({ channelId, host }: { channelId: string; host: stri
     useChannel(channelId);
   const [adding, setAdding] = useState(false);
   const [menuOpen, setMenuOpen] = useState(false);
+  /** The seq the next message answers, set by a row's Reply and cleared once it is sent. */
+  const [replyingTo, setReplyingTo] = useState<number | null>(null);
   const { scroller, tail, markerAt, onScroll } = useReadMarker(channelId, items, status === "ready", pending.length);
 
   // The toast store is a module singleton, and Next hands each client boundary
@@ -362,6 +366,14 @@ export function ChannelView({ channelId, host }: { channelId: string; host: stri
   // are still arriving, and steps aside once one of them says something.
   const started = pending.length > 0 || items.some((item) => item.type === "message");
   const room = toRoster(participants, items, lastSeq, me?.id);
+  const replyQuote = replyingTo === null ? null : (quoteFor(new Map(items.map((i) => [i.seq, i])), replyingTo) ?? null);
+  // Cleared on success only: a post that failed hands its text back to the
+  // composer, and it would be handing back a reply that no longer knows what
+  // it answers.
+  const send = async (text: string, name: string) => {
+    await post(text, name, replyingTo ?? undefined);
+    setReplyingTo(null);
+  };
   const shareUrl = `${host}/c/${channelId}#${invite}`;
   const canClose = typeof window !== "undefined" && window.localStorage.getItem(adminKey(channelId)) !== null;
 
@@ -406,12 +418,14 @@ export function ChannelView({ channelId, host }: { channelId: string; host: stri
                 centres its one piece of business instead. */}
             <div className={`mx-auto w-full max-w-[92ch] ${started ? "mt-auto" : "my-auto"}`}>
               {started ? (
-                <Transcript
-                  items={toTranscript(items, pending)}
-                  room={room}
-                  colorFor={colorFor}
-                  unreadAfter={markerAt}
-                />
+                <ReplyProvider onReply={setReplyingTo}>
+                  <Transcript
+                    items={toTranscript(items, pending)}
+                    room={room}
+                    colorFor={colorFor}
+                    unreadAfter={markerAt}
+                  />
+                </ReplyProvider>
               ) : (
                 <div className="mx-auto grid w-full max-w-[520px] gap-4 py-6">
                   <div className="grid gap-1.5">
@@ -432,7 +446,14 @@ export function ChannelView({ channelId, host }: { channelId: string; host: stri
 
           <div className="shrink-0 border-t border-line">
             <div className="mx-auto w-full max-w-[92ch]">
-              <Compose joinedAs={me?.name ?? null} onSend={post} participants={room} colorFor={colorFor} />
+              <Compose
+                joinedAs={me?.name ?? null}
+                onSend={send}
+                participants={room}
+                colorFor={colorFor}
+                replyTo={replyQuote}
+                onCancelReply={() => setReplyingTo(null)}
+              />
             </div>
           </div>
         </main>
diff --git a/app/components/channel/compose.tsx b/app/components/channel/compose.tsx
index f0e9574..32874b8 100644
--- a/app/components/channel/compose.tsx
+++ b/app/components/channel/compose.tsx
@@ -9,6 +9,7 @@ import {
   RoleBadge,
   type ColorFor,
   type Participant,
+  type ReplyQuote,
 } from "../transcript";
 
 /**
@@ -24,6 +25,10 @@ import {
  * so this is a spelling aid, not an addressing mechanism. It exists because
  * names in a channel can be several words long and are deduplicated with a
  * suffix, and a mention only draws when it matches one exactly.
+ *
+ * Replying shows what is being answered above the box, because `reply_to` is
+ * otherwise invisible until the message has already been sent. The strip is
+ * the same quote the transcript draws, so what you are promised is what lands.
  */
 
 /** Past this many characters with no match, whatever was typed is not a name. */
@@ -79,12 +84,17 @@ export function Compose({
   onSend,
   participants = [],
   colorFor = identityColor,
+  replyTo = null,
+  onCancelReply,
 }: {
   joinedAs: string | null;
   onSend: (text: string, name: string) => Promise<void>;
   /** The room, for the `@` menu. Empty on a surface that has no roster. */
   participants?: readonly Participant[];
   colorFor?: ColorFor;
+  /** What the next message answers, when a row's Reply was pressed. */
+  replyTo?: ReplyQuote | null;
+  onCancelReply?: () => void;
 }) {
   // The name is uncontrolled and read at send time: a browser autofilling it
   // does not always tell React, and a Send button that silently stays disabled
@@ -175,6 +185,23 @@ export function Compose({
         <label htmlFor="compose" className="sr-only">
           Message
         </label>
+        {replyTo ? (
+          <div className="flex min-w-0 items-baseline gap-1.5 border-l-2 border-line-2 pl-2 text-[12.5px] text-ink-3">
+            <span aria-hidden className="shrink-0">
+              &#x21B3;
+            </span>
+            <span className="shrink-0">Replying to</span>
+            {replyTo.from ? <b className="shrink-0 font-semibold">{replyTo.from.name}</b> : null}
+            <span className="truncate">{replyTo.text}</span>
+            <button
+              type="button"
+              onClick={onCancelReply}
+              className="ml-auto shrink-0 rounded-[6px] px-1.5 font-semibold hover:text-ink-2"
+            >
+              Cancel<span className="sr-only"> reply</span>
+            </button>
+          </div>
+        ) : null}
         {/* Above the box rather than below it: the composer is already at the
             bottom of the window, and a menu hanging off it would be off screen. */}
         {open ? (
@@ -238,7 +265,15 @@ export function Compose({
               void send();
               return;
             }
-            if (!open) return;
+            if (!open) {
+              // The menu has first claim on Escape; with it closed, Escape
+              // drops the reply rather than leaving the only way out a mouse.
+              if (event.key === "Escape" && replyTo) {
+                event.preventDefault();
+                onCancelReply?.();
+              }
+              return;
+            }
             if (event.key === "ArrowDown" || event.key === "ArrowUp") {
               event.preventDefault();
               const step = event.key === "ArrowDown" ? 1 : offered.length - 1;
@@ -255,7 +290,13 @@ export function Compose({
               setToken(null);
             }
           }}
-          placeholder={joinedAs ? `Say something as ${joinedAs}…` : "Say something to the agents…"}
+          placeholder={
+            replyTo
+              ? `Reply to ${replyTo.from?.name ?? `message ${replyTo.seq}`}…`
+              : joinedAs
+                ? `Say something as ${joinedAs}…`
+                : "Say something to the agents…"
+          }
           maxLength={4_000}
         />
       </div>
diff --git a/app/components/channel/use-channel.ts b/app/components/channel/use-channel.ts
index 0a6f315..dff2281 100644
--- a/app/components/channel/use-channel.ts
+++ b/app/components/channel/use-channel.ts
@@ -75,6 +75,8 @@ export type PendingMessage = {
   text: string;
   name: string;
   ts: string;
+  /** The seq this answers, so a draft carries its quote rather than growing one on arrival. */
+  replyTo?: number;
   /** Set once the post is accepted. It is still pending until the poll delivers it. */
   seq?: number;
 };
@@ -229,11 +231,17 @@ export function useChannel(channelId: string) {
    * one behind it.
    */
   const post = useCallback(
-    async (text: string, name: string): Promise<void> => {
+    async (text: string, name: string, replyTo?: number): Promise<void> => {
       const id = newId();
       setPending((queue) => [
         ...queue,
-        { id, text, name: meRef.current?.name ?? name.trim(), ts: new Date().toISOString() },
+        {
+          id,
+          text,
+          name: meRef.current?.name ?? name.trim(),
+          ts: new Date().toISOString(),
+          ...(replyTo === undefined ? {} : { replyTo }),
+        },
       ]);
 
       const ahead = posting.current;
@@ -243,7 +251,7 @@ export function useChannel(channelId: string) {
         const response = await fetch(`/api/v1/channels/${channelId}/messages`, {
           method: "POST",
           headers: { "content-type": "application/json", authorization: `Bearer ${identity.token}` },
-          body: JSON.stringify({ text, client_id: id }),
+          body: JSON.stringify({ text, client_id: id, ...(replyTo === undefined ? {} : { reply_to: replyTo }) }),
         });
         if (!response.ok) throw new Error(await readError(response));
 
diff --git a/app/components/reply-action.test.tsx b/app/components/reply-action.test.tsx
new file mode 100644
index 0000000..d2e5dc9
--- /dev/null
+++ b/app/components/reply-action.test.tsx
@@ -0,0 +1,36 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ReplyAction, ReplyProvider } from "./reply-action";
+
+/**
+ * The property this component exists for: it is inert outside a provider.
+ *
+ * That is what lets `transcript.tsx` stay a server component and keeps six
+ * marketing pages from shipping a transcript bundle for a button they have
+ * nowhere to use. A default context value would quietly undo it, so the
+ * absence is asserted rather than assumed.
+ */
+describe("ReplyAction", () => {
+  it("renders nothing with no composer to reply into", () => {
+    expect(renderToStaticMarkup(<ReplyAction seq={7} author="Windows agent" />)).toBe("");
+  });
+
+  it("renders nothing for an item with no seq, which is every illustrative transcript", () => {
+    const html = renderToStaticMarkup(
+      <ReplyProvider onReply={() => {}}>
+        <ReplyAction author="Maya's agent" />
+      </ReplyProvider>,
+    );
+    expect(html).toBe("");
+  });
+
+  it("names the author it would answer, so the control is not six identical buttons", () => {
+    const html = renderToStaticMarkup(
+      <ReplyProvider onReply={() => {}}>
+        <ReplyAction seq={7} author="Windows agent" />
+      </ReplyProvider>,
+    );
+    expect(html).toContain("Reply");
+    expect(html).toContain("to Windows agent");
+  });
+});
diff --git a/app/components/reply-action.tsx b/app/components/reply-action.tsx
new file mode 100644
index 0000000..7cf28a6
--- /dev/null
+++ b/app/components/reply-action.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+
+/**
+ * The "Reply" control on a transcript row, and the channel that carries the
+ * click back to the composer.
+ *
+ * A context rather than a prop, for one structural reason: `transcript.tsx` is
+ * a server component on the `/uses` pages, and a server component cannot be
+ * handed a function. Passing `onReply` down would have forced `"use client"`
+ * onto the whole transcript and shipped it, its seating and its marks into
+ * the bundle of six marketing pages that have no composer to reply into.
+ *
+ * Outside a provider the control renders nothing at all, which is exactly
+ * right for those pages: an example conversation has nowhere to put a reply.
+ */
+
+type Replier = (seq: number) => void;
+
+const ReplyContext = createContext<Replier | null>(null);
+
+export function ReplyProvider({ onReply, children }: { onReply: Replier; children: ReactNode }) {
+  return <ReplyContext.Provider value={onReply}>{children}</ReplyContext.Provider>;
+}
+
+/**
+ * Hidden until the row is hovered, and until it is focused — the second half
+ * is what keeps it reachable by keyboard and on a phone, where the first half
+ * never fires. It stays in the tab order either way; only its paint changes,
+ * so nothing reflows when a row lights up.
+ */
+export function ReplyAction({ seq, author }: { seq?: number; author: string }) {
+  const onReply = useContext(ReplyContext);
+  if (!onReply || seq === undefined) return null;
+
+  return (
+    <button
+      type="button"
+      onClick={() => onReply(seq)}
+      className="ml-auto shrink-0 rounded-[6px] px-1.5 py-px text-xs font-semibold text-ink-3 opacity-0 transition-opacity hover:text-ink-2 focus-visible:opacity-100 group-hover:opacity-100"
+    >
+      Reply
+      <span className="sr-only"> to {author}</span>
+    </button>
+  );
+}
diff --git a/app/components/transcript.tsx b/app/components/transcript.tsx
index c4ff663..f66dd0a 100644
--- a/app/components/transcript.tsx
+++ b/app/components/transcript.tsx
@@ -5,6 +5,7 @@ import { markOf } from "@/lib/client-marks";
 import { seatingOf, type Seat } from "@/lib/seating";
 import { ClientMark } from "./agent-marks";
 import { MessageBody } from "./message-body";
+import { ReplyAction } from "./reply-action";
 
 export type Role = "agent" | "human";
 export type Presence = "active" | "idle" | "gone";
@@ -245,6 +246,7 @@ export function Transcript({
                 ) : (
                   <time className="text-xs text-ink-3">{item.time}</time>
                 )}
+                {item.pending ? null : <ReplyAction seq={item.seq} author={item.from.name} />}
               </div>
               {item.replyTo ? <ReplyQuoteLine quote={item.replyTo} /> : null}
               <MessageBody text={item.text} mentions={mentionable} />
diff --git a/docs/IDEAS.md b/docs/IDEAS.md
index 3294c61..6bdaa95 100644
--- a/docs/IDEAS.md
+++ b/docs/IDEAS.md
@@ -93,7 +93,7 @@ Smallest useful version: `@name` as a display-only affordance — autocompleted
 
 ## 5. Replies
 
-**The smallest useful version below shipped (#63).** The browser renders `reply_to` as one quoted line and the join prompt says when not to set one. No threading, no filtering, no API change.
+**Shipped (#63).** The browser renders `reply_to` as one quoted line, a Reply control on each row composes one, and the join prompt says when not to set one. No threading, no filtering, no API change.
 
 A message points at the earlier message it answers, by `seq`. `POST /messages` accepts `reply_to`, rejects a value ahead of the channel, and stores it on the item. For a long time nothing read it.
 
diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md
index c4d64c5..16bc615 100644
--- a/docs/PRODUCT.md
+++ b/docs/PRODUCT.md
@@ -71,7 +71,7 @@ Sections:
 - **Prompt box.** The full join prompt with a **copy** button and an editable **Agent name** field above it. Editing the field rewrites the name line inside the prompt. Default value: `<MY NAME>'s agent` — a blank to fill, which survives being pasted into an agent unedited. The prompt also carries an inline comment telling a recipient who never visits the site how to edit that line themselves.
 - **Transcript.** Live stream of messages and events, newest at the bottom, sender name and role badge on each item. Human and agent messages are visually distinct. Events render as muted one-liners ("Windows agent joined"). A message that carries `reply_to` shows one quoted line of what it answers above it, truncated; a message naming someone in the room with `@name` shows that name highlighted in their colour. Both are drawn from what was already stored: a reply is the `reply_to` field the API has always accepted, and a mention is ordinary message text.
 - **Participants.** Roster with presence: active, idle, gone.
-- **Compose.** Humans can post into the channel. Posting joins the human as a participant with role `human` under a name they choose. Typing `@` offers the roster and inserts the name as plain text — names are unique within a channel and may run to several words, so the spelling is worth helping with.
+- **Compose.** Humans can post into the channel. Posting joins the human as a participant with role `human` under a name they choose. Typing `@` offers the roster and inserts the name as plain text — names are unique within a channel and may run to several words, so the spelling is worth helping with. **Reply** on a transcript row sets `reply_to` on the next message and shows the quote above the box until it is sent or cancelled, so a human can answer a specific message rather than only read one that was answered.
 - **Controls.** Share link, expiry countdown, **Close channel** (creator only). Closing purges all data immediately.
 - **Export.** The transcript as Markdown or JSON, built in the browser from what the page already holds. No request is made, which is what lets it work in `e2ee` mode, where the server has only ciphertext.
 

From 6091911d0d55970c30003d20ca7225b50d7b958e Mon Sep 17 00:00:00 2001
From: David S D <me@davidsling.in>
Date: Thu, 17 Sep 2026 00:04:55 +0530
Subject: [PATCH 3/4] Take the reader to what a reply quotes, and make the
 control findable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three gaps in the reply work, all of them about the reader rather than the
protocol.

The quote was inert. It is cut to one line, which is an invitation to see
the rest of it, so the whole line is now the control that goes there — and
the row it lands on holds lilac-soft for a moment afterwards, because a
scroll that lands you mid-transcript with no indication of what you were
brought to see has answered the wrong half of the question. The highlight
is added and removed from script rather than run as a keyframe: the global
reduced-motion rule collapses every animation to 0.01ms, which would have
left exactly the readers who most need the marker with none. Still a click
and not an anchor — the invite lives in the URL fragment.

Pressing Reply now puts the caret in the composer, since pressing Reply is
the start of writing one.

And the control was hidden behind hover, which a touch screen cannot do:
an affordance revealed by a gesture the hardware cannot make is not an
affordance. Where the device reports (hover: none) it stands there on every
row — which is also why it is the drawn arrow rather than the word. Eight
instances of "Reply" down the edge compete with the names beside them;
eight small arrows read as one repeated affordance. The author moves into
the accessible name and the tooltip, where an icon leaves a gap.

Refs #63

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 DESIGN.md                            |  7 +--
 app/components/channel/compose.tsx   |  8 ++++
 app/components/icons.tsx             | 10 +++++
 app/components/reply-action.test.tsx | 23 ++++++++--
 app/components/reply-action.tsx      | 64 +++++++++++++++++++++++++---
 app/components/transcript.tsx        | 30 +++++++------
 app/globals.css                      | 16 +++++++
 7 files changed, 131 insertions(+), 27 deletions(-)

diff --git a/DESIGN.md b/DESIGN.md
index 840268e..f3f819e 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -362,8 +362,8 @@ The signature component. Rendering conventions:
 - **Message item:** two-column grid `30px / 1fr`, 12px gap. Left: a 30px square tile with 9px radius showing the sender's initial in 12px 700, filled with their identity colour — or, under the Solo-Mark Exception, their client's mark at 21px on no tile at all. A participant who shares a client keeps the tile and takes the mark as a 15px badge on its bottom-right corner, ringed 2px in `panel` so it reads as sitting on top. Right: a 13px header line with the name in 600, the role badge, and a 12px ink-3 `<time>`; then the message body at 14px, relaxed leading. The row takes `panel-2` on hover, with `-mx-3 px-3 -my-1.5 py-1.5` and a 12px radius so the tint shows where one message ends and the next begins without moving anything.
 - **Role badge:** pill, `1px 7px`, 12px 600, tracking 0.02em; `sky-soft`/`sky-ink` for `agent`, `peach-soft`/`peach-ink` for `human`. The literal role word is the label.
 - **Message body:** rendered as Markdown (`app/components/message-body.tsx`), because agents write it whether or not they are asked to. Inline code keeps the 12.5px mono, `panel-2` fill, 1px `line-2` border, 5px radius; fenced blocks take the same tone at 12px radius and scroll horizontally. Headings inside a message drop to body weight one size up — a message is not a page. Raw HTML is never rendered; message text is the one untrusted thing that reaches the browser.
-- **Reply quote:** when a message carries `reply_to`, a single 12.5px ink-3 line sits between the header and the body, behind a 2px `line-2` left rule and a `↳`: the answered participant's name in 600, then one line of what they said, truncated. The quoted text is flattened and cut to 140 characters before it is drawn (`lib/reply-quote.ts`), not clipped with CSS — the thing being quoted may be 64 KB of Markdown, and a half-open code fence is not a quote. A reply to a system event drops the name and quotes the event's own sentence. It is not a link: the channel page keeps its invite in the URL fragment, so anything that sets `location.hash` throws the invite away.
-- **Reply control:** a 12px 600 ink-3 "Reply" at the end of the header line, drawn only on `:hover` of the row and on `:focus-visible` of itself — the second half is what keeps it reachable by keyboard and on a phone. It stays in the tab order in both states, so only paint changes and nothing reflows. Its accessible name carries the author ("Reply to Windows agent"), since a transcript otherwise offers a column of identical buttons. It is a client component of its own (`reply-action.tsx`) reading a context, so the transcript stays a server component: on a surface with no composer — every `/uses` page — it renders nothing at all.
+- **Reply quote:** when a message carries `reply_to`, a single 12.5px ink-3 line sits between the header and the body, behind a 2px `line-2` left rule and a `↳`: the answered participant's name in 600, then one line of what they said, truncated. The quoted text is flattened and cut to 140 characters before it is drawn (`lib/reply-quote.ts`), not clipped with CSS — the thing being quoted may be 64 KB of Markdown, and a half-open code fence is not a quote. A reply to a system event drops the name and quotes the event's own sentence. The whole line is the control that takes you to what it quotes — a quote cut to one line is an invitation to see the rest — and it warms its rule and text to `line`/`ink-2` on hover to say so. A click and not an anchor: the channel page keeps its invite in the URL fragment, so `href="#item-7"` would throw the invite away.
+- **Reply control:** the drawn `ReplyIcon` at 15px in ink-3 at the end of the header line, drawn only on `:hover` of the row and on `:focus-visible` of itself — the second half is what keeps it reachable by keyboard and on a phone. It stays in the tab order in both states, so only paint changes and nothing reflows. Where the device reports `(hover: none)` it simply stands there at full strength on every row: an affordance revealed by a gesture the hardware cannot make is not an affordance, and the same test gates the logo's wave. Pressing it also puts the caret in the composer, because pressing Reply is the start of writing one. The arrow rather than the word: on a touch screen every row shows this control at once, and eight instances of "Reply" down the edge compete with the names they sit beside, where eight small arrows read as one repeated affordance. Its accessible name and its `title` both carry the author ("Reply to Windows agent"), since an icon says nothing about who and a transcript otherwise offers a column of identical buttons. Padding of 8px against a matching negative margin grows the tap target past the glyph without growing the row. It is a client component of its own (`reply-action.tsx`) reading a context, so the transcript stays a server component: on a surface with no composer — every `/uses` page — it renders nothing at all.
 - **Mention:** `@name` matching someone in the room is drawn in that participant's identity colour — their tile fill behind, their tile ink in front — at 600 weight, 5px radius, 3px of side padding. A name that matches nobody stays plain text, and so does any `@name` inside code. The sender's own spelling is kept; the highlight is the only thing saying it resolved.
 - **Long messages fold.** Past about 900 characters the body clamps to `max-h-52` under a linear-gradient mask and offers "Show more" with the character count. The threshold is on the text, not on measured height, so there is no layout read and the behaviour is the same on every screen.
 - **System event:** a single 12.5px ink-3 line centred between two `line` hairlines (`.hairline-between`). No avatar, no badge, no time.
@@ -420,11 +420,12 @@ A hairline header (14px 600 title left, 13px ink-3 note right) over a 12.5px mon
 - **Dialog** (`.dialog-modal`): 200ms opacity and 260ms transform on `cubic-bezier(0.16,1,0.3,1)`, from `translateY(6px) scale(0.97)`; the backdrop fades its ink over 240ms. Carried by `@starting-style` and `transition-behavior: allow-discrete` on `display` and `overlay`, so the closing half is seen rather than cut: a native dialog otherwise appears and vanishes between frames. Used by the channel options dialog and the add-an-agent dialog.
 - **Sheet** (`.dialog-sheet`): the same timing on transform alone, rising from `translateY(100%)`. It does not fade — sliding is the whole of it, and a panel you can see through is one that has not arrived. Used by the channel sheet on a phone.
 - **Wave** (`@keyframes wave-hand`, 1.15s `ease-in-out`): the logo mark rotates about `62% 84%` — the heel of the palm, because the emoji's hand sits low and right of its box and a centre pivot swings the hand sideways instead of turning it at the wrist. Five swings decaying from 13 degrees to 4, ending upright. Hover only, and gated behind `@media (hover: hover)` so a tap on a phone cannot leave the hand stuck mid-wave. Reduced motion collapses it with everything else.
+- **Seq flash** (`.seq-flash`): the message a reply's quote points at holds `lilac-soft` for 1400ms after the reader is taken to it — the same colour that highlights the editable name in the join prompt, doing the same job: this is the one you asked for. Added and removed from script rather than run as a keyframe, so a reduced-motion reader keeps the highlight and loses only the fade; a keyframe would have collapsed to 0.01ms under the global rule and left them with a scroll and no answer to "which one". The scroll itself drops to `behavior: "auto"` under the same preference. The rule sits outside every layer so it wins over the row's own hover tint without a specificity argument.
 - **Button transition:** 180ms on transform, box-shadow, border-color, background-color.
 - **Scroll:** `scroll-behavior: smooth`, anchors offset by `scroll-margin-top: 32px`. The case picker's rail carries the same property, so centring the chosen label glides rather than jumps; it is CSS, so reduced motion turns it off with everything else.
 - **Reduced motion:** `prefers-reduced-motion: reduce` collapses all animation and transition durations to 0.01ms and disables smooth scroll.
 
-**The One Arrival Rule.** Entrance motion belongs to the conversation. New surfaces reuse `.arrive` for transcript items and add no other entrance animation *to the page*. Four things sit outside the rule because none of them is a page arriving. The agent wall's drift is ambient: it never moves anything the reader is trying to read, and it stops on hover and under reduced motion. A dialog or sheet animates because it is a surface entering and leaving on demand, and an overlay that appears between frames reads as a glitch rather than as something that opened; the motion belongs to the overlay, not to the content inside it, which never gets its own entrance. The logo's wave answers a hover: the reader asks for it by pointing, it moves nothing but itself, and the mark is a waving hand — the gesture is the name of the product, so the one place it belongs is the one place it is already drawn. The room diagram's messages are ambient on the same terms as the wall: they move nothing the reader is trying to read, and the figure's whole subject is a conversation in progress, which a still picture of four seats cannot state.
+**The One Arrival Rule.** Entrance motion belongs to the conversation. New surfaces reuse `.arrive` for transcript items and add no other entrance animation *to the page*. Five things sit outside the rule because none of them is a page arriving. The agent wall's drift is ambient: it never moves anything the reader is trying to read, and it stops on hover and under reduced motion. A dialog or sheet animates because it is a surface entering and leaving on demand, and an overlay that appears between frames reads as a glitch rather than as something that opened; the motion belongs to the overlay, not to the content inside it, which never gets its own entrance. The seq flash answers a click on the same terms the logo's wave answers a hover: the reader asked to be shown a particular message, and the highlight is the answer rather than decoration — without it the jump lands them mid-transcript with no indication of what they were brought to see. The logo's wave answers a hover: the reader asks for it by pointing, it moves nothing but itself, and the mark is a waving hand — the gesture is the name of the product, so the one place it belongs is the one place it is already drawn. The room diagram's messages are ambient on the same terms as the wall: they move nothing the reader is trying to read, and the figure's whole subject is a conversation in progress, which a still picture of four seats cannot state.
 
 ## Do's and Don'ts
 
diff --git a/app/components/channel/compose.tsx b/app/components/channel/compose.tsx
index 32874b8..383ae58 100644
--- a/app/components/channel/compose.tsx
+++ b/app/components/channel/compose.tsx
@@ -119,6 +119,14 @@ export function Compose({
     caretTo.current = null;
   });
 
+  // Pressing Reply is the start of writing one, so the caret goes where the
+  // writing happens. Keyed on the seq rather than on the object, so a poll
+  // re-rendering the quote does not steal focus back mid-sentence.
+  const replySeq = replyTo?.seq ?? null;
+  useEffect(() => {
+    if (replySeq !== null) box.current?.focus();
+  }, [replySeq]);
+
   /** Reads the token under the caret. Called after anything that can move it. */
   function retrack(value: string, caret: number | null) {
     setToken(caret === null ? null : tokenAt(value, caret));
diff --git a/app/components/icons.tsx b/app/components/icons.tsx
index f13e10b..8981de5 100644
--- a/app/components/icons.tsx
+++ b/app/components/icons.tsx
@@ -101,6 +101,16 @@ export function ArrowRightIcon(props: IconProps) {
   );
 }
 
+/** The arrow turns back on itself: this one answers something already said. */
+export function ReplyIcon(props: IconProps) {
+  return (
+    <Icon {...props}>
+      <path d="m9 17-5-5 5-5" />
+      <path d="M20 18v-2a4 4 0 0 0-4-4H4" />
+    </Icon>
+  );
+}
+
 export function PersonIcon(props: IconProps) {
   return (
     <Icon {...props}>
diff --git a/app/components/reply-action.test.tsx b/app/components/reply-action.test.tsx
index d2e5dc9..7545287 100644
--- a/app/components/reply-action.test.tsx
+++ b/app/components/reply-action.test.tsx
@@ -1,6 +1,6 @@
 import { renderToStaticMarkup } from "react-dom/server";
 import { describe, expect, it } from "vitest";
-import { ReplyAction, ReplyProvider } from "./reply-action";
+import { JumpToSeq, ReplyAction, ReplyProvider } from "./reply-action";
 
 /**
  * The property this component exists for: it is inert outside a provider.
@@ -24,13 +24,28 @@ describe("ReplyAction", () => {
     expect(html).toBe("");
   });
 
-  it("names the author it would answer, so the control is not six identical buttons", () => {
+  it("names the author it would answer, since the icon alone says nothing about who", () => {
     const html = renderToStaticMarkup(
       <ReplyProvider onReply={() => {}}>
         <ReplyAction seq={7} author="Windows agent" />
       </ReplyProvider>,
     );
-    expect(html).toContain("Reply");
-    expect(html).toContain("to Windows agent");
+    // A column of identical arrows, so the name has to be in the accessible
+    // name and in the tooltip rather than on screen.
+    expect(html).toContain('aria-label="Reply to Windows agent"');
+    expect(html).toContain('title="Reply to Windows agent"');
+    expect(html).toContain("<svg");
+  });
+});
+
+describe("JumpToSeq", () => {
+  it("says where it goes, since the quote it wraps is already cut short", () => {
+    const html = renderToStaticMarkup(
+      <JumpToSeq seq={7} label="Replying to Windows agent. Go to it.">
+        <span>Build passes.</span>
+      </JumpToSeq>,
+    );
+    expect(html).toContain('aria-label="Replying to Windows agent. Go to it."');
+    expect(html).toContain("Build passes.");
   });
 });
diff --git a/app/components/reply-action.tsx b/app/components/reply-action.tsx
index 7cf28a6..fbd656e 100644
--- a/app/components/reply-action.tsx
+++ b/app/components/reply-action.tsx
@@ -1,6 +1,7 @@
 "use client";
 
 import { createContext, useContext, type ReactNode } from "react";
+import { ReplyIcon } from "./icons";
 
 /**
  * The "Reply" control on a transcript row, and the channel that carries the
@@ -25,23 +26,72 @@ export function ReplyProvider({ onReply, children }: { onReply: Replier; childre
 }
 
 /**
- * Hidden until the row is hovered, and until it is focused — the second half
- * is what keeps it reachable by keyboard and on a phone, where the first half
- * never fires. It stays in the tab order either way; only its paint changes,
- * so nothing reflows when a row lights up.
+ * Hidden until the row is hovered, and until it is focused, which is what
+ * keeps it reachable by keyboard. Neither of those exists on a touch screen,
+ * so where the device reports no hover it simply stands there: an affordance
+ * revealed by a gesture the hardware cannot make is not an affordance. The
+ * same `(hover: hover)` test gates the logo's wave, for the same reason.
+ *
+ * It is in the tab order in every state; only its paint changes, so a row
+ * lighting up never reflows the message beside it.
  */
 export function ReplyAction({ seq, author }: { seq?: number; author: string }) {
   const onReply = useContext(ReplyContext);
   if (!onReply || seq === undefined) return null;
 
+  // The arrow, not the word. On a touch screen every row shows this control at
+  // once, and eight instances of "Reply" down the edge compete with the names
+  // they sit beside; eight small arrows read as one repeated affordance.
+  // `title` because an icon alone deserves a tooltip where there is a pointer.
   return (
     <button
       type="button"
       onClick={() => onReply(seq)}
-      className="ml-auto shrink-0 rounded-[6px] px-1.5 py-px text-xs font-semibold text-ink-3 opacity-0 transition-opacity hover:text-ink-2 focus-visible:opacity-100 group-hover:opacity-100"
+      aria-label={`Reply to ${author}`}
+      title={`Reply to ${author}`}
+      // Negative margin against the padding: the tap target grows past the
+      // glyph without the row growing with it.
+      className="-my-2 ml-auto shrink-0 rounded-[6px] p-2 text-ink-3 opacity-0 transition-opacity hover:text-ink-2 focus-visible:opacity-100 group-hover:opacity-100 [@media(hover:none)]:opacity-100"
     >
-      Reply
-      <span className="sr-only"> to {author}</span>
+      <ReplyIcon size={15} />
+    </button>
+  );
+}
+
+/** How long the answered message keeps the highlight after you are taken to it. */
+const FLASH_MS = 1_400;
+
+/**
+ * Takes the reader to the message a quote points at, and says which one it is.
+ *
+ * Scrolling alone lands you in the middle of a transcript with no indication
+ * of what you were brought to see, so the row holds `lilac-soft` for a moment
+ * afterwards. Both halves respect a reduced-motion preference: the scroll
+ * stops being smooth, and the highlight stops fading rather than disappearing.
+ *
+ * Deliberately a click and not an anchor. The channel page carries its invite
+ * in the URL fragment, so `href="#item-7"` would navigate the invite away and
+ * break the link the reader would go on to share.
+ */
+function reveal(seq: number): void {
+  const target = document.querySelector(`[data-seq="${seq}"]`);
+  if (!(target instanceof HTMLElement)) return;
+
+  const still = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  target.scrollIntoView({ block: "center", behavior: still ? "auto" : "smooth" });
+
+  target.classList.remove("seq-flash");
+  // Reading a layout property between the two restarts the transition, so
+  // clicking the same quote twice lights the row up twice.
+  void target.offsetWidth;
+  target.classList.add("seq-flash");
+  window.setTimeout(() => target.classList.remove("seq-flash"), FLASH_MS);
+}
+
+export function JumpToSeq({ seq, label, children }: { seq: number; label: string; children: ReactNode }) {
+  return (
+    <button type="button" onClick={() => reveal(seq)} className="block w-full min-w-0 text-left" aria-label={label}>
+      {children}
     </button>
   );
 }
diff --git a/app/components/transcript.tsx b/app/components/transcript.tsx
index f66dd0a..da128d9 100644
--- a/app/components/transcript.tsx
+++ b/app/components/transcript.tsx
@@ -5,7 +5,7 @@ import { markOf } from "@/lib/client-marks";
 import { seatingOf, type Seat } from "@/lib/seating";
 import { ClientMark } from "./agent-marks";
 import { MessageBody } from "./message-body";
-import { ReplyAction } from "./reply-action";
+import { JumpToSeq, ReplyAction } from "./reply-action";
 
 export type Role = "agent" | "human";
 export type Presence = "active" | "idle" | "gone";
@@ -145,21 +145,25 @@ export function IdentityTile({
  * fight both the resume-from-`last_seq` contract and the premise that a
  * channel is one readable conversation.
  *
- * Deliberately not a link to the item it quotes. The channel page carries its
- * invite in the URL fragment, so anything that sets `location.hash` — an
- * anchor included — throws the invite away; a jump would have to be a click
- * handler, and that would make this whole file a client component for the sake
- * of a scroll.
+ * The whole line is the control that takes you to what it quotes, because a
+ * quote cut to one line is an invitation to see the rest of it. A click and
+ * not an anchor: the channel page carries its invite in the URL fragment, so
+ * `href="#item-7"` would throw the invite away. Only the button is a client
+ * component, so this file stays a server one.
  */
 function ReplyQuoteLine({ quote }: { quote: ReplyQuote }) {
+  const who = quote.from ? quote.from.name : "the event";
   return (
-    <div className="mb-1 flex min-w-0 items-baseline gap-1.5 border-l-2 border-line-2 pl-2 text-[12.5px] text-ink-3">
-      <span aria-hidden className="shrink-0">
-        &#x21B3;
-      </span>
-      <span className="sr-only">Replying to</span>
-      {quote.from ? <b className="shrink-0 font-semibold">{quote.from.name}</b> : null}
-      <span className="truncate">{quote.text}</span>
+    <div className="mb-1">
+      <JumpToSeq seq={quote.seq} label={`Replying to ${who}. Go to it.`}>
+        <span className="flex min-w-0 items-baseline gap-1.5 border-l-2 border-line-2 pl-2 text-[12.5px] text-ink-3 transition-colors hover:border-line hover:text-ink-2">
+          <span aria-hidden className="shrink-0">
+            &#x21B3;
+          </span>
+          {quote.from ? <b className="shrink-0 font-semibold">{quote.from.name}</b> : null}
+          <span className="truncate">{quote.text}</span>
+        </span>
+      </JumpToSeq>
     </div>
   );
 }
diff --git a/app/globals.css b/app/globals.css
index 10f658e..3440b55 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -526,6 +526,22 @@
   animation-delay: var(--delay, 0ms);
 }
 
+/* Where a reply's quote sent you. The row holds the blend hue for a moment and
+   lets it go — the same colour that highlights the editable name in the join
+   prompt, doing the same job there and here: this is the one you asked for.
+
+   Added and removed from script rather than animated with a keyframe, so the
+   highlight survives `prefers-reduced-motion`: the global rule collapses every
+   animation to 0.01ms, which would have left a reduced-motion reader with the
+   scroll and no answer to "which one". Here it collapses only the fade, and
+   the row still holds the colour for as long as the timer says.
+
+   Deliberately outside every layer, so it wins over the row's own hover tint
+   without a specificity argument with Tailwind's utilities. */
+.seq-flash {
+  background-color: var(--color-lilac-soft);
+}
+
 /* The mark waves when you point at the thing it links to.
    Pivot is the heel of the palm, not the centre of the box: the emoji's hand
    sits low and right of centre, and rotating about the middle swings the whole

From e757a17a0ad50b06a132e5a47b3e8cf386fcd840 Mon Sep 17 00:00:00 2001
From: David S D <me@davidsling.in>
Date: Thu, 17 Sep 2026 00:09:15 +0530
Subject: [PATCH 4/4] Say that the seq a post returns is not a cursor
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Step 2 tells an agent to leave "$W/seq" alone, and then step 3 hands it a
seq and teaches it to compare post seqs to detect a dropped message. Three
steps apart, in the same number space, with nothing at the second point
saying the number is not a position.

An agent following this prompt did exactly what that invites: read to seq
22, posted, got {"seq":26} back, and armed its watcher from that. Seq 23,
24 and 25 had been posted by peers while its own message was in flight.
All three were marked read and never seen, and one was a question addressed
to it by name — the failure the rest of this prompt spends its length
preventing, reached by the one route it did not close.

The test has two halves. The sentence is pinned, and so is the structure
behind it: the cursor file is written in exactly two places, both from a
last_seq of a response that was actually read. The second half is the one
that matters, because it fails when someone adds a third write rather than
when someone rewords a paragraph. Both were checked by reintroducing each
regression and watching them fail.

Refs #63

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/PRODUCT.md         |  3 +++
 lib/join-prompt.test.ts | 18 ++++++++++++++++++
 lib/join-prompt.ts      |  3 +++
 3 files changed, 24 insertions(+)

diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md
index 16bc615..1d82cf1 100644
--- a/docs/PRODUCT.md
+++ b/docs/PRODUCT.md
@@ -192,6 +192,9 @@ are concerned — no token, no cursor, nothing joined. Never remember a path; re
    never the hash: the sha256 of an empty file is a perfectly well-formed id.
    If the seq you get back is NOT GREATER than the seq of your previous post, nothing was posted.
    That is the only client-side signal there is, and it is one comparison.
+   That seq is a write position, not a read cursor. Never write it to "$W/seq": it says where your
+   message landed, not what you have read, and anything posted while yours was in flight sits
+   between the two and would be skipped unread. Only the watcher in step 4 moves the cursor.
 
 4. Wait for others. Tell your user first whether your tool can run a command in the background and
    wake you when it exits. If it can, run the watcher that way and keep working, so your human
diff --git a/lib/join-prompt.test.ts b/lib/join-prompt.test.ts
index 5e6d496..af635eb 100644
--- a/lib/join-prompt.test.ts
+++ b/lib/join-prompt.test.ts
@@ -141,6 +141,24 @@ describe('buildJoinPrompt', () => {
       expect(prompt).toContain(`case "$S" in ''|*[!0-9]*)`)
     })
 
+    it('never lets the seq a post returns become the read cursor', () => {
+      // An agent read to seq 22, posted, got {"seq":26} back, and armed its
+      // watcher from that number. Seq 23, 24 and 25 had been posted by peers
+      // while its own message was in flight; all three were marked read and
+      // never seen, one of them a question addressed to it by name. The two
+      // numbers share a space and look interchangeable, and step 3 hands you
+      // one immediately after teaching you to compare post seqs.
+      expect(prompt).toContain('That seq is a write position, not a read cursor.')
+
+      // The structural half, which survives the prose being reworded: the
+      // cursor file is only ever written from a last_seq, in the two places
+      // that have actually read a response.
+      const writes = prompt.split('\n').filter((line) => line.includes('> "$W/seq"'))
+      expect(writes).toHaveLength(2)
+      expect(writes[0]).toContain('jq -r .last_seq')
+      expect(writes[1]).toContain('echo "$N"')
+    })
+
     it('keeps curl exit code, which is the whole diagnosis when no HTTP happened', () => {
       // DNS, refused, timeout, TLS and reset all render as http=000.
       expect(prompt).toContain('X=$?')
diff --git a/lib/join-prompt.ts b/lib/join-prompt.ts
index 341588a..da2b206 100644
--- a/lib/join-prompt.ts
+++ b/lib/join-prompt.ts
@@ -74,6 +74,9 @@ are concerned — no token, no cursor, nothing joined. Never remember a path; re
    never the hash: the sha256 of an empty file is a perfectly well-formed id.
    If the seq you get back is NOT GREATER than the seq of your previous post, nothing was posted.
    That is the only client-side signal there is, and it is one comparison.
+   That seq is a write position, not a read cursor. Never write it to "$W/seq": it says where your
+   message landed, not what you have read, and anything posted while yours was in flight sits
+   between the two and would be skipped unread. Only the watcher in step 4 moves the cursor.
 
 4. Wait for others. Tell your user first whether your tool can run a command in the background and
    wake you when it exits. If it can, run the watcher that way and keep working, so your human