@astrosheep/square 0.3.73 → 0.3.75

package/plugins/paseo/client/markdown.tsx

@@ -0,0 +1,221 @@
+import { useMemo } from "react";
+import { Text, View, type TextStyle } from "react-native";
+import type { PluginTheme } from "@getpaseo/plugin";
+
+interface InlinePart { text: string; bold?: boolean; italic?: boolean; code?: boolean }
+
+// Minimal inline grammar: **bold**, *italic*, `code`. The first marker wins;
+// no nesting, so action lines like *leans over* survive intact.
+const INLINE_RE = /(\*\*[^*\n]+\*\*|\*[^*\n]+\*|`[^`\n]+`)/g;
+
+export function parseInline(line: string): InlinePart[] {
+  const parts: InlinePart[] = [];
+  let last = 0;
+  for (const match of line.matchAll(INLINE_RE)) {
+    const index = match.index ?? 0;
+    if (index > last) parts.push({ text: line.slice(last, index) });
+    const token = match[0];
+    if (token.startsWith("**")) parts.push({ text: token.slice(2, -2), bold: true });
+    else if (token.startsWith("`")) parts.push({ text: token.slice(1, -1), code: true });
+    else parts.push({ text: token.slice(1, -1), italic: true });
+    last = index + token.length;
+  }
+  if (last < line.length) parts.push({ text: line.slice(last) });
+  return parts;
+}
+
+type Block =
+  | { kind: "code"; text: string }
+  | { kind: "heading"; level: number; text: string }
+  | { kind: "quote"; lines: string[] }
+  | { kind: "list"; items: string[] }
+  | { kind: "paragraph"; text: string };
+
+function parseBlocks(markdown: string): Block[] {
+  const lines = markdown.replace(/\r\n/g, "\n").split("\n");
+  const blocks: Block[] = [];
+  let paragraph: string[] = [];
+  const flushParagraph = () => {
+    if (paragraph.length > 0) blocks.push({ kind: "paragraph", text: paragraph.join(" ") });
+    paragraph = [];
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (line.trimStart().startsWith("```")) {
+      flushParagraph();
+      const body: string[] = [];
+      i += 1;
+      while (i < lines.length && !lines[i]!.trimStart().startsWith("```")) { body.push(lines[i]!); i += 1; }
+      blocks.push({ kind: "code", text: body.join("\n") });
+      continue;
+    }
+    const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (heading) {
+      flushParagraph();
+      blocks.push({ kind: "heading", level: heading[1]!.length, text: heading[2]! });
+      continue;
+    }
+    if (line.startsWith(">")) {
+      flushParagraph();
+      const quote: string[] = [];
+      while (i < lines.length && lines[i]!.startsWith(">")) { quote.push(lines[i]!.replace(/^>\s?/, "")); i += 1; }
+      i -= 1;
+      blocks.push({ kind: "quote", lines: quote });
+      continue;
+    }
+    if (/^\s*(?:[-*+]|\d+\.)\s+/.test(line)) {
+      flushParagraph();
+      const items: string[] = [];
+      while (i < lines.length && /^\s*(?:[-*+]|\d+\.)\s+/.test(lines[i]!)) {
+        const item = /^\s*(?:[-*+]|\d+\.)\s+(.*)$/.exec(lines[i]!);
+        items.push(item?.[1] ?? lines[i]!);
+        i += 1;
+      }
+      i -= 1;
+      blocks.push({ kind: "list", items });
+      continue;
+    }
+    if (line.trim() === "") { flushParagraph(); continue; }
+    paragraph.push(line.trim());
+  }
+  flushParagraph();
+  return blocks;
+}
+
+interface SquareBlock { meta?: string; actor?: string; body: string }
+
+// A square notification is one or more <square-activity> blocks. Split them out so the
+// envelope lines become styled chrome and only the body goes through markdown.
+function parseSquareBlocks(text: string): SquareBlock[] {
+  const blocks: SquareBlock[] = [];
+  const re = /<square-activity>\n([\s\S]*?)\n<\/square-activity>/g;
+  let last = 0;
+  for (const match of text.matchAll(re)) {
+    const index = match.index ?? 0;
+    const before = text.slice(last, index).trim();
+    if (before !== "") blocks.push({ body: before });
+    const inner = match[1]!;
+    const innerLines = inner.split("\n");
+    const meta = innerLines[0]?.startsWith("· ") ? innerLines.shift() : undefined;
+    const actor = innerLines[0]?.startsWith("● ") ? innerLines.shift() : undefined;
+    blocks.push({ meta, actor, body: innerLines.join("\n").trim() });
+    last = index + match[0].length;
+  }
+  const rest = text.slice(last).trim();
+  if (rest !== "") blocks.push({ body: rest });
+  if (blocks.length === 0) blocks.push({ body: text });
+  return blocks;
+}
+
+export function SquareMarkdown({ text, theme }: { text: string; theme: PluginTheme }) {
+  const { colors } = theme;
+  const styles = useMemo(() => ({
+    block: { gap: 6 },
+    paragraph: { color: colors.foreground, fontSize: 13, lineHeight: 20 },
+    bold: { fontWeight: "700" as const },
+    italic: { fontStyle: "italic" as const },
+    inlineCode: {
+      fontFamily: "Menlo",
+      fontSize: 12,
+      backgroundColor: colors.surface2,
+      color: colors.foreground,
+    },
+    codeBlock: {
+      backgroundColor: colors.surface0,
+      borderRadius: 8,
+      borderWidth: 1,
+      borderColor: colors.border,
+      paddingHorizontal: 9,
+      paddingVertical: 7,
+    },
+    codeText: { fontFamily: "Menlo", fontSize: 11.5, lineHeight: 17, color: colors.foreground },
+    heading: { color: colors.foreground, fontWeight: "700" as const },
+    quote: {
+      borderLeftWidth: 2,
+      borderLeftColor: colors.border,
+      paddingLeft: 8,
+      gap: 2,
+    },
+    quoteText: { color: colors.foregroundMuted, fontSize: 13, lineHeight: 20, fontStyle: "italic" as const },
+    meta: { color: colors.foregroundMuted, fontSize: 11, lineHeight: 15, fontFamily: "Menlo" },
+    actor: { color: colors.accent, fontSize: 12, lineHeight: 17 },
+    separator: { height: 1, backgroundColor: colors.border, marginVertical: 4 },
+    listRow: { flexDirection: "row" as const, gap: 6 },
+    bullet: { color: colors.accent, fontSize: 13, lineHeight: 20 },
+  }), [colors]);
+
+  const renderInline = (line: string, keyPrefix: string, extra?: TextStyle) => (
+    <Text key={keyPrefix} style={[styles.paragraph, extra]}>
+      {parseInline(line).map((part, index) => (
+        <Text
+          key={`${keyPrefix}-${index}`}
+          style={[
+            part.bold ? styles.bold : undefined,
+            part.italic ? styles.italic : undefined,
+            part.code ? styles.inlineCode : undefined,
+          ]}
+        >{part.code ? ` ${part.text} ` : part.text}</Text>
+      ))}
+    </Text>
+  );
+
+  const renderBlock = (block: Block, key: string) => {
+    switch (block.kind) {
+      case "code":
+        return (
+          <View key={key} style={styles.codeBlock}>
+            <Text selectable style={styles.codeText}>{block.text}</Text>
+          </View>
+        );
+      case "heading":
+        return renderInline(block.text, key, { fontSize: Math.max(13, 18 - block.level), fontWeight: "700" });
+      case "quote":
+        return (
+          <View key={key} style={styles.quote}>
+            {block.lines.map((line, index) => (
+              <Text key={`${key}-${index}`} style={styles.quoteText}>{line}</Text>
+            ))}
+          </View>
+        );
+      case "list":
+        return (
+          <View key={key} style={{ gap: 2 }}>
+            {block.items.map((item, index) => (
+              <View key={`${key}-${index}`} style={styles.listRow}>
+                <Text style={styles.bullet}>•</Text>
+                <Text style={[styles.paragraph, { flexShrink: 1 }]}>
+                  {parseInline(item).map((part, partIndex) => (
+                    <Text
+                      key={partIndex}
+                      style={[
+                        part.bold ? styles.bold : undefined,
+                        part.italic ? styles.italic : undefined,
+                        part.code ? styles.inlineCode : undefined,
+                      ]}
+                    >{part.code ? ` ${part.text} ` : part.text}</Text>
+                  ))}
+                </Text>
+              </View>
+            ))}
+          </View>
+        );
+      case "paragraph":
+        return renderInline(block.text, key);
+    }
+  };
+
+  const blocks = useMemo(() => parseSquareBlocks(text), [text]);
+
+  return (
+    <View style={styles.block}>
+      {blocks.map((block, blockIndex) => (
+        <View key={blockIndex} style={styles.block}>
+          {blockIndex > 0 && <View style={styles.separator} />}
+          {block.meta !== undefined && <Text style={styles.meta}>{block.meta}</Text>}
+          {block.actor !== undefined && <Text style={styles.actor}>{block.actor}</Text>}
+          {parseBlocks(block.body).map((inner, innerIndex) => renderBlock(inner, `${blockIndex}-${innerIndex}`))}
+        </View>
+      ))}
+    </View>
+  );
+}

package/plugins/paseo/client/square-message.tsx

@@ -1,117 +1,87 @@
 import type { PluginTimelineItemProps } from "@getpaseo/plugin/client";
-import { copyText, Icon, useToast } from "@getpaseo/plugin/client/react-native";
+import { Icon } from "@getpaseo/plugin/client/react-native";
 import { useMemo, useState } from "react";
-import { Platform, Pressable, ScrollView, Text, View } from "react-native";
+import { Pressable, ScrollView, Text, View } from "react-native";
 import { squareHeadline, type SquareMessageData } from "../shared/message";
+import { parseInline, SquareMarkdown } from "./markdown";
 
-function withOpacity(color: string, opacity: number): string {
-  const hex = /^#([\da-f]{3}|[\da-f]{6})$/iu.exec(color);
-  if (hex === null) return color;
-  const value = hex[1]!.length === 3 ? [...hex[1]!].map((part) => part + part).join("") : hex[1]!;
-  const alpha = Math.round(opacity * 255).toString(16).padStart(2, "0");
-  return `#${value}${alpha}`;
-}
-
+/** A plain card: who, what they did, where, then what they said. No badge, no chrome — the words carry the place. */
 export function SquareMessage({ item, theme, layout }: PluginTimelineItemProps<SquareMessageData>) {
   const [expanded, setExpanded] = useState(false);
-  const toast = useToast();
-  const { text, items } = item.data;
+  const { text, fullText, items } = item.data;
   const latest = items?.[items.length - 1];
+  // Preview typography only; expansion prefers the complete renderer-only text.
   const preview = latest?.preview?.replace(/\s+/g, " ").trim();
   const muted = theme.colors.foregroundMuted;
   const foreground = theme.colors.foreground;
+
   const styles = useMemo(() => ({
-    marker: { color: theme.colors.accent, fontSize: 10, marginTop: 2 },
-    headline: { color: foreground, fontSize: 13, lineHeight: 19, flexShrink: 1 },
-    meta: { color: muted, fontSize: 11, lineHeight: 16, flexShrink: 1 },
-    preview: { color: foreground, fontSize: 12, lineHeight: 18, flexShrink: 1 },
-    bodyPanel: {
+    card: {
+      marginVertical: 3,
+      marginRight: layout.compact ? 0 : 8,
       backgroundColor: theme.colors.surface1,
-      borderRadius: 12,
-      marginTop: 5,
-      marginLeft: 17,
-      overflow: "hidden" as const,
+      borderWidth: 1,
+      borderColor: theme.colors.border,
+      borderRadius: 6,
+      paddingHorizontal: 12,
+      paddingVertical: 8,
+      gap: 4,
     },
-    bodyText: {
-      color: foreground,
-      fontSize: 12,
-      lineHeight: 21,
-      fontFamily: Platform.OS === "ios" ? "Menlo" : "monospace",
-      paddingHorizontal: layout.compact ? 10 : 12,
-      paddingTop: 8,
-    },
-  }), [foreground, layout.compact, muted, theme.colors.accent, theme.colors.surface1]);
+    whoRow: { flexDirection: "row" as const, alignItems: "baseline" as const, gap: 6 },
+    glyph: { color: theme.colors.accent, fontSize: 9 },
+    actor: { color: foreground, fontSize: 12.5, fontWeight: "600" as const },
+    route: { color: muted, fontSize: 12.5, flexShrink: 1 },
+    count: { color: muted, fontSize: 11 },
+    preview: { color: foreground, fontSize: 13, lineHeight: 19 },
+    action: { color: muted, fontStyle: "italic" as const },
+    bold: { fontWeight: "700" as const },
+    code: { fontFamily: "Menlo", fontSize: 12 },
+  }), [foreground, layout.compact, muted, theme.colors.accent, theme.colors.border, theme.colors.surface1]);
+
+  const headline = latest !== undefined ? squareHeadline(latest) : "Square context";
+  const routeText = latest?.actor !== undefined && headline.startsWith(latest.actor)
+    ? headline.slice(latest.actor.length).trim()
+    : headline;
 
   return (
-    <View>
-      <View>
-        <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 7, paddingVertical: 2 }}>
-          <Text style={styles.marker}>■</Text>
-          <Text numberOfLines={1} style={styles.headline}>
-            {latest?.square ?? "Square context"}
+    <View style={styles.card}>
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`${expanded ? "收起" : "展开"} ${latest?.square ?? "square"}: ${headline}`}
+        aria-expanded={expanded}
+        onPress={() => setExpanded(value => !value)}
+        style={({ pressed }) => ({ gap: 4, opacity: pressed ? 0.7 : 1 })}
+      >
+        <View style={styles.whoRow}>
+          <Text style={styles.glyph}>■</Text>
+          {latest?.actor !== undefined && <Text style={styles.actor}>{latest.actor}</Text>}
+          <Text numberOfLines={1} style={styles.route}>
+            {routeText}{latest?.square !== undefined && ` · ${latest.square}`}
           </Text>
-          {items && items.length > 1 && <Text style={styles.meta}>· {items.length} landed</Text>}
           <View style={{ flex: 1 }} />
-          {!expanded && <Pressable
-            accessibilityRole="button"
-            accessibilityLabel={`展开 ${latest !== undefined ? squareHeadline(latest) : "Square context"}`}
-            aria-expanded={false}
-            onPress={() => setExpanded(true)}
-            hitSlop={6}
-            style={({ pressed }) => ({ padding: 5, opacity: pressed ? 0.6 : 1 })}
-          >
-            <Icon name="ChevronDown" size={18} color={muted} />
-          </Pressable>}
+          {items !== undefined && items.length > 1 && <Text style={styles.count}>{items.length}</Text>}
+          <Icon name={expanded ? "ChevronUp" : "ChevronDown"} size={16} color={muted} />
         </View>
-        {(latest?.actor !== undefined || preview) && <View style={{ marginLeft: 17, marginTop: 2 }}>
-          <Text numberOfLines={1} style={styles.preview}>
-            <Text style={{ color: theme.colors.accent, fontSize: 10 }}>● </Text>
-            {latest?.actor !== undefined && <Text style={styles.meta}>{latest.actor} </Text>}
-            {preview}
+        {!expanded && preview !== undefined && preview !== "" && (
+          <Text numberOfLines={2} style={styles.preview}>
+            {parseInline(preview).map((part, index) => (
+              <Text
+                key={index}
+                style={[
+                  part.italic ? styles.action : undefined,
+                  part.bold ? styles.bold : undefined,
+                  part.code ? styles.code : undefined,
+                ]}
+              >{part.text}</Text>
+            ))}
           </Text>
-        </View>}
-      </View>
-      {expanded && <View style={styles.bodyPanel}>
-        <ScrollView style={{ maxHeight: layout.compact ? 280 : 400 }} nestedScrollEnabled>
-          <Text selectable style={styles.bodyText}>{text}</Text>
+        )}
+      </Pressable>
+      {expanded && (
+        <ScrollView style={{ maxHeight: layout.compact ? 280 : 400, marginTop: 2 }} nestedScrollEnabled>
+          <SquareMarkdown text={fullText ?? text} theme={theme} />
         </ScrollView>
-        <View style={{
-          marginHorizontal: layout.compact ? 10 : 12,
-          marginTop: 5,
-          borderTopWidth: 1,
-          borderTopColor: withOpacity(theme.colors.border, 0.55),
-          paddingVertical: 3,
-          flexDirection: "row",
-          alignItems: "center",
-          justifyContent: "space-between",
-        }}>
-          <Pressable
-            accessibilityRole="button"
-            accessibilityLabel="Copy Square content"
-            onPress={() => { void copyText(text).catch(() => toast.error("Could not copy Square content")); }}
-            style={({ pressed }) => ({
-              flexDirection: "row",
-              alignItems: "center",
-              gap: 5,
-              paddingHorizontal: 2,
-              opacity: pressed ? 0.6 : 1,
-            })}
-          >
-            <Icon name="Copy" size={12} color={muted} />
-            <Text style={{ color: muted, fontSize: 11 }}>Copy content</Text>
-          </Pressable>
-          <Pressable
-            accessibilityRole="button"
-            accessibilityLabel="收起 Square context"
-            aria-expanded={true}
-            onPress={() => setExpanded(false)}
-            hitSlop={6}
-            style={({ pressed }) => ({ paddingHorizontal: 5, paddingVertical: 1, opacity: pressed ? 0.6 : 1 })}
-          >
-            <Icon name="ChevronUp" size={18} color={muted} />
-          </Pressable>
-        </View>
-      </View>}
+      )}
     </View>
   );
 }

package/plugins/paseo/client/transform.ts

@@ -17,7 +17,10 @@ export const transformSquareMessage: PluginTimelineTransformerContribution<"tool
       version: 1,
       data: {
         text: item.detail.text,
-        ...(details.success ? { items: details.data.items } : {}),
+        ...(details.success ? {
+          items: details.data.items,
+          ...(details.data.fullText === undefined ? {} : { fullText: details.data.fullText }),
+        } : {}),
       },
     }],
   };

package/plugins/paseo/shared/message.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 export const squareCardDetailsSchema = z.object({
+  fullText: z.string().optional(),
   items: z.array(z.object({
     square: z.string(),
     actor: z.string().optional(),
@@ -16,15 +17,16 @@ export function squareHeadline(item: z.output<typeof squareCardDetailsSchema>["i
   if (item.actor === undefined || item.route === undefined) return item.description;
   const to = item.recipient;
   switch (item.route) {
-    case "mention": return to === undefined ? `${item.actor} mentioned you` : `${item.actor} mentioned ${to}`;
-    case "reply": return to === undefined ? `${item.actor} replied to you` : `${item.actor} replied to ${to}`;
-    case "attention": return `New from ${item.actor}`;
-    case "bell": return `${item.actor} called everyone`;
+    case "mention": return to === undefined ? `${item.actor} spoke your name` : `${item.actor} spoke ${to}'s name`;
+    case "reply": return to === undefined ? `${item.actor} answered you` : `${item.actor} answered ${to}`;
+    case "attention": return to === undefined ? `${item.actor} spoke · you're listening` : `${item.actor} spoke · ${to} is listening`;
+    case "bell": return `${item.actor} rang the bell`;
   }
 }
 
 export const squareMessageSchema = z.object({
   text: z.string(),
+  fullText: z.string().optional(),
   items: squareCardDetailsSchema.shape.items.optional(),
 });
 export type SquareMessageData = z.output<typeof squareMessageSchema>;

package/plugins/pi/square-pi.js

@@ -1,9 +1,10 @@
 import path from 'node:path';
+import { Text } from '@earendil-works/pi-tui';
 
 import { presentPendingAtBoundary, renderPendingAtBoundary } from '../../dist/boundary-presentation.js';
 import { automaticSessionEnd, automaticSessionStart } from '../../dist/automatic-session.js';
 import { sessionInbox, observeSessionPending } from '../../dist/inbox.js';
-import { previewAttentionBody, renderAttentionDescription } from '../../dist/attention-presentation.js';
+import { previewAttentionBody, renderAttentionDescription, renderAttentionFull } from '../../dist/attention-presentation.js';
 import { createPiReceiver, sendPiMessage } from '../../dist/packages/agent-delivery/src/pi.js';
 
 class PiDeliveryDroppedError extends Error {
@@ -31,7 +32,7 @@ function framePiMessage(content) {
   return `\n${content.replace(/^\n+/, '').replace(/\n+$/, '')}\n`;
 }
 
-/** Renderer-only facts for the collapsed card; Pi never sends `details` to the model. */
+/** Renderer-only summary and full text; Pi never sends `details` to the model. */
 export function pendingCardDetails(pending) {
   const items = pending.flatMap((membership) => membership.notifications.map((note) => ({
     square: path.basename(membership.squarePath, '.square'),
@@ -41,7 +42,14 @@ export function pendingCardDetails(pending) {
     preview: previewAttentionBody(note.body),
     description: renderAttentionDescription({ actor: note.actor, recipient: membership.name, route: note.route }),
   })));
-  return items.length === 0 ? undefined : { items };
+  if (items.length === 0) return undefined;
+  const fullText = pending.flatMap((membership) => membership.notifications.map((note) => renderAttentionFull({
+    squarePath: membership.squarePath,
+    actIndex: note.actIndex,
+    recipient: membership.name,
+    ...note,
+  }))).join('\n\n');
+  return { items, fullText };
 }
 
 // Conservative terminal width: anything outside ASCII counts as two columns, so a
@@ -62,12 +70,17 @@ function fitColumns(text, columns) {
 }
 
 /**
- * Collapsed: one line naming who reached you and where. Expanded: Pi's default card,
- * which shows the exact content the model received.
+ * Collapsed: one line naming who reached you and where. Expanded: the complete
+ * notification text from renderer details, wrapped by Pi's terminal component.
  */
 export function renderSquareCard(message, { expanded, outputPad = 1 }, theme) {
+  if (expanded) {
+    return typeof message.details?.fullText === 'string'
+      ? new Text(message.details.fullText, outputPad, 0)
+      : undefined;
+  }
   const items = message.details?.items;
-  if (expanded || !Array.isArray(items) || items.length === 0) return undefined;
+  if (!Array.isArray(items) || items.length === 0) return undefined;
   const [first] = items;
   const tail = ` · ${first.square}${items.length > 1 ? ` +${items.length - 1}` : ''}`;
   return {
@@ -240,8 +253,8 @@ export default function squarePiExtension(pi) {
             boundSessionId,
             async (content) => {
               if (signal.aborted || currentRunSignal?.aborted) throw new Error('Pi notification delivery cancelled');
-              // One card for the human: collapsed it names who reached you, expanded it
-              // shows the same content the model receives.
+              // One card for the human: a compact heading, expandable to the full body.
+              // Model context stays bounded; renderer-only details carry the complete text.
               const messageContent = framePiMessage(content);
               const landing = waitForLanding(messageContent, signal, 'steer');
               try {
@@ -254,16 +267,13 @@ export default function squarePiExtension(pi) {
               }
               return landing.promise;
             },
-            async (id, env) => {
-              const inbox = await sessionInbox(id, env ?? sessionEnv(id));
+            async (_id, _env, boundarySignal) => {
+              // Recheck committed revisions and current bindings before reusing observed content.
+              const inbox = await observer.read({ signal: boundarySignal, excludeKeys: handledPending });
               if (signal.aborted || token !== generation) return [];
               for (const key of inboxKeys(inbox)) observedPending.add(key);
-              return inbox.map((membership) => ({
-                ...membership,
-                notifications: membership.notifications.filter((note) => !handledPending.has(
-                  `${membership.squarePath}\u0000${membership.name.toLocaleLowerCase()}\u0000${note.actIndex}`,
-                )),
-              }));
+              pending = inbox;
+              return inbox;
             },
             env,
             signal,

package/skills/square/SKILL.md

@@ -65,7 +65,7 @@ The ownership boundary belongs here. Does this match your read?
 EOF
 ```
 
-**Addressing.** Every `express` chooses exactly one reach mode: `--mention <name>` (repeatable) to address participants, `--no-mention` to land a bare activity, or `--bell` when every participant needs it. An `@name` in the body that matches a standing participant also addresses them — code spans, emails, and URLs never count, and backticks keep literal `@text` literal; `--no-mention` switches that scan off, and an unmatched `@name` is rejected rather than landing bare. Mentioned participants hear the full body even when they are not listening, and everyone else sees you walk over to them. `listen` opts a participant into future bare delivery. Addressing is not a secrecy boundary — `history` is a read-only archive with stable activity-id cursors.
+**Addressing.** Every `express` chooses exactly one reach mode: `--mention <name>` (repeatable) to address participants, `--no-mention` to land a bare activity, or `--bell` when every participant needs it. An `@name` in the body that matches a standing participant also addresses them — code spans, emails, and URLs never count, and backticks keep literal `@text` literal; `--no-mention` switches that scan off. An unmatched `@name` stays ordinary body text and never blocks landing; only standing matches become recipients. Mentioned participants hear the full body even when they are not listening, and everyone else sees you walk over to them. `listen` opts a participant into future bare delivery. Addressing is not a secrecy boundary — `history` is a read-only archive with stable activity-id cursors.
 
 Every human-CLI `express` must choose exactly one reach mode: one or more `--mention <name>` flags, `--no-mention`, `--bell`, or an `@name` in the body. The CLI rejects an omitted mode and rejects combining these flag modes. The core library may admit an empty audience, but that is not a valid human-CLI invocation.