@astrosheep/square 0.3.77 → 0.3.78

package/dist/attention-presentation.d.ts

@@ -11,7 +11,7 @@ export interface AttentionPreview {
 export declare function previewAttentionBody(body: string): string;
 export declare function attentionBodyIsClipped(body: string): boolean;
 export declare function displayAttentionPath(squarePath: string): string;
-export declare function renderAttentionDescription({ actor, recipient, route }: Pick<AttentionPreview, 'actor' | 'recipient' | 'route'>): string;
+export declare function renderAttentionDescription({ actor, route }: Pick<AttentionPreview, 'actor' | 'route'>): string;
 /** Full notification text for human-facing expansion, never the bounded model preview. */
 export declare function renderAttentionFull(attention: AttentionPreview): string;
 export declare function renderAttentionPreview(attention: AttentionPreview): string;

package/dist/attention-presentation.js

@@ -1,6 +1,5 @@
 import { homedir } from 'node:os';
 import { formatActivityId } from './square-core.js';
-import { participantCommandPrefix } from './presentation.js';
 export const ATTENTION_BODY_MAX = 200;
 export function previewAttentionBody(body) {
     const compact = body.replace(/\r\n/g, '\n');
@@ -16,12 +15,12 @@ export function displayAttentionPath(squarePath) {
         ? `~${squarePath.slice(homedir().length)}`
         : squarePath;
 }
-export function renderAttentionDescription({ actor, recipient, route }) {
+export function renderAttentionDescription({ actor, route }) {
     switch (route) {
-        case 'mention': return `${actor} spoke your name (${recipient})`;
-        case 'reply': return `${actor} answered you (${recipient})`;
-        case 'attention': return `${actor} spoke · you’re listening to ${actor}`;
-        case 'bell': return `${actor} rang the bell · everyone’s attention`;
+        case 'mention': return `${actor} spoke your name`;
+        case 'reply': return `${actor} answered you`;
+        case 'attention': return `${actor} spoke · you’re listening`;
+        case 'bell': return `${actor} rang the bell`;
     }
 }
 /** Full notification text for human-facing expansion, never the bounded model preview. */
@@ -31,7 +30,7 @@ export function renderAttentionFull(attention) {
 function renderAttentionBlock(attention, body) {
     return [
         '<square-activity>',
-        `· ${displayAttentionPath(attention.squarePath)} · ${formatActivityId(attention.actIndex)}`,
+        `· ${displayAttentionPath(attention.squarePath)} · ${attention.recipient} · ${formatActivityId(attention.actIndex)}`,
         `● ${renderAttentionDescription(attention)}`,
         '',
         body,
@@ -41,10 +40,8 @@ function renderAttentionBlock(attention, body) {
 export function renderAttentionPreview(attention) {
     return [
         renderAttentionBlock(attention, previewAttentionBody(attention.body)),
-        // A clipped body ends with the full command to read it all: a labeled caption, then the
-        // command bare on its own line so it can be copied and run as it is.
         ...(attentionBodyIsClipped(attention.body)
-            ? ['· clipped — read it all:', `${participantCommandPrefix(attention.squarePath, attention.recipient)} catch --id ${formatActivityId(attention.actIndex)}`]
+            ? ['· clipped — catch it to read the rest']
             : []),
     ].join('\n');
 }

package/dist/boundary-presentation.js

@@ -46,6 +46,7 @@ function renderBoundary(inbox) {
     const blocks = [];
     const complete = [];
     let omitted = 0;
+    const omission = (count) => `… ${count} more — catch up to read them`;
     for (const [index, entry] of queued.entries()) {
         const { membership, notification } = entry;
         const block = [
@@ -59,7 +60,7 @@ function renderBoundary(inbox) {
             }),
         ].join('\n');
         const omittedAfter = omitted + queued.length - index - 1;
-        const prospective = frameBoundary([...blocks, block, ...(omittedAfter > 0 ? [`… ${omittedAfter} ${omittedAfter === 1 ? 'notification' : 'notifications'} omitted.`] : [])]);
+        const prospective = frameBoundary([...blocks, block, ...(omittedAfter > 0 ? [omission(omittedAfter)] : [])]);
         if (prospective.length > CONTEXT_MAX) {
             omitted += 1;
             continue;
@@ -72,7 +73,7 @@ function renderBoundary(inbox) {
         });
     }
     return {
-        context: frameBoundary([...blocks, ...(omitted > 0 ? [`… ${omitted} ${omitted === 1 ? 'notification' : 'notifications'} omitted.`] : [])]),
+        context: frameBoundary([...blocks, ...(omitted > 0 ? [omission(omitted)] : [])]),
         complete,
     };
 }

package/dist/cli/maintenance-commands.js

@@ -1,5 +1,5 @@
 import { createSquareApplication } from '../square-application.js';
-import { renderDoctorClean, renderDoctorUnfixable, withPathOutput } from '../presentation.js';
+import { commandPrefix, renderDoctorClean, renderDoctorUnfixable, withPathOutput } from '../presentation.js';
 import { requireSquarePath, usage } from './context.js';
 export const migrateCommand = {
     parse(argv, context) {
@@ -32,7 +32,7 @@ export const doctorCommand = {
         const squarePath = requireSquarePath(context);
         const { data: diagnosis, projection } = await createSquareApplication({ cwd: context.cwd, env: context.env, squarePath }).diagnose();
         if (diagnosis.migrationRequired !== undefined) {
-            return { output: withPathOutput(squarePath, `${diagnosis.migrationRequired}\n`), exitCode: 2 };
+            return { output: withPathOutput(squarePath, `${diagnosis.migrationRequired}\n${commandPrefix(squarePath)} migrate\n`), exitCode: 2 };
         }
         if (diagnosis.unfixable !== undefined || diagnosis.standingCount === undefined) {
             return {

package/dist/cli/program.js

@@ -8,11 +8,17 @@ async function handleSquareError(error, context) {
         throw error;
     const detail = error.operation;
     const squarePath = context?.squarePath;
-    const recovery = context === undefined || squarePath === undefined ? undefined
+    const recovery = error.facts?.reason === 'migration_required' || context === undefined || squarePath === undefined ? undefined
         : await applicationFor({ ...context, name: detail?.participant ?? context.name }).recovery().catch(() => undefined);
     const name = detail?.participant ?? recovery?.data.participant ?? context?.name;
     const existing = [refusalText(error)];
-    if (squarePath !== undefined && name !== undefined && error.code === 'already_joined') {
+    if (error.facts?.reason === 'migration_required') {
+        if (error.facts.ledgerRoot !== undefined)
+            existing.push('square ledger migrate', 'square ledger verify');
+        else if (squarePath !== undefined)
+            existing.push(`${commandPrefix(squarePath)} migrate`);
+    }
+    else if (squarePath !== undefined && name !== undefined && error.code === 'already_joined') {
         existing.splice(0, 1, `✕ ${participantIdentity(name)} shoos you out of the square`, `  · ${participantIdentity(name)} already stands here — another session holds the name`);
         existing.push(...takeoverRecoveryLines(squarePath, name));
     }

package/dist/host-ledger-migration.js

@@ -5,7 +5,7 @@ import { DatabaseSync } from 'node:sqlite';
 import { canonicalPathSync } from './canonical-path.js';
 import { withFileLock } from './file-lock.js';
 import { hostLedgerRoot } from './host-ledger-root.js';
-import { LEDGER_FILENAME, initializeLedger, insertLedgerRecord, ledgerRecordColumns, setLedgerRevisions, upgradeLedger, validateLedger, verifyLedger, inspectLedgerIdentity, } from './host-ledger-sqlite.js';
+import { LEDGER_FILENAME, initializeLedger, insertLedgerRecord, ledgerRecordColumns, setLedgerRevisions, upgradeLedger, validateLedger, verifyLedger, inspectLedgerIdentity, migrationRequired, } from './host-ledger-sqlite.js';
 import { inSqliteTransaction } from './sqlite-transaction.js';
 function rootFor(options) {
     return canonicalPathSync(options.rootPath ?? hostLedgerRoot(options.env));
@@ -25,10 +25,6 @@ async function exists(file) {
         throw error;
     }
 }
-function migrationGuidance(root, file) {
-    const name = file ?? path.join(root, LEDGER_FILENAME);
-    return `Host ledger at ${root} has a supported older format (${name}).\nStop agent sessions and MCP services using Square with this ledger; keep them stopped until migration and verification succeed; then start them with the updated Square version.\nsquare ledger migrate\nsquare ledger verify`;
-}
 function verificationFailure(root, file, format) {
     const name = file ?? path.join(root, LEDGER_FILENAME);
     const detail = format === 'unsupported'
@@ -62,7 +58,7 @@ async function verifyDatabase(file, root, signal) {
             db = undefined;
         }
         if (format === 'old-sqlite')
-            throw new Error(migrationGuidance(root, file));
+            throw migrationRequired(root);
         throw verificationFailure(root, file, format);
     }
     finally {

package/dist/host-ledger-sqlite.js

@@ -3,7 +3,7 @@ import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { nameKey } from './model.js';
+import { SquareError, nameKey } from './model.js';
 import { inSqliteTransaction, retrySqliteBusy } from './sqlite-transaction.js';
 export const LEDGER_FILENAME = 'host-ledger.sqlite';
 export const LEDGER_APPLICATION_ID = 0x5351484c;
@@ -175,7 +175,7 @@ catch (error) {
     throw error;
 } }
 export function migrationRequired(root) {
-    return new Error(`Host ledger legacy format needs offline migration at ${root}.\nStop agent sessions and MCP services using Square with this ledger; keep them stopped until migration and verification succeed; then start them with the updated Square version.\nRun square ledger migrate from the same environment, then square ledger verify.`);
+    return new SquareError('invalid_args', `Host ledger at ${root} needs offline migration.\nStop sessions and MCP services using it, back it up, then migrate and verify from the same environment before restarting.`, { reason: 'migration_required', ledgerRoot: root });
 }
 /** Compact runtime framing. Full schema, projections and integrity belong to explicit verify. */
 function validateLedgerHeader(db, version = LEDGER_VERSION) {

package/dist/model.d.ts

@@ -24,6 +24,8 @@ export interface SquareErrorFacts {
     reason?: 'never_joined' | 'not_standing' | 'bell_mention_conflict' | 'not_addressed' | 'migration_required' | 'explicit_reach_required' | 'invalid_reply' | 'invalid_done_body';
     /** The activity id a `catch --id` refusal named. */
     activityId?: string;
+    /** The host ledger requiring offline migration, rather than the selected artifact. */
+    ledgerRoot?: string;
     /** Requested recipient spellings, without parsing presentation copy. */
     targets?: readonly string[];
     /** Whether the artifact holds that activity at all; an unknown id needs an ordinary page. */

package/dist/square-sqlite.d.ts

@@ -25,17 +25,11 @@ export interface LegacyFraming {
     readonly userVersion: number;
     readonly journalMode: string;
 }
-/**
- * The one recovery command for an owned legacy artifact, with a shell-quoted
- * path. Kept beside framing recognition so the refusal and migration
- * instruction cannot drift apart. This codec stays free of the renderer.
- */
-export declare function migrationRecoveryCommand(location: string): string;
 /**
  * Read-only legacy framing: application id, format version, journal mode and the
  * exact owned snapshot schema. It decodes no snapshot payload, writes no pragma
- * and runs no DDL, so ordinary open can establish ownership before offering
- * the migration command. Anything else is unrelated or unsupported, not repaired.
+ * and runs no DDL, so ordinary open can establish ownership before requiring
+ * migration. Anything else is unrelated or unsupported, not repaired.
  */
 export declare function validateLegacyFraming(database: DatabaseSync, applicationId: number, location?: string): LegacyFraming;
 export declare const SCHEMA_SQL = "CREATE TABLE square_meta (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  revision INTEGER NOT NULL CHECK (revision BETWEEN 0 AND 9007199254740991),\n  next_act_index INTEGER NOT NULL CHECK (next_act_index BETWEEN 0 AND 9007199254740991),\n  hard_cap INTEGER CHECK (hard_cap BETWEEN 1 AND 9007199254740991),\n  throttle_per_minute INTEGER CHECK (throttle_per_minute BETWEEN 1 AND 9007199254740991),\n  preamble_json TEXT NOT NULL CHECK (json_valid(preamble_json)),\n  warmup_json TEXT NOT NULL CHECK (json_valid(warmup_json))\n);\nCREATE TABLE activities (\n  act_index INTEGER PRIMARY KEY CHECK (act_index BETWEEN 0 AND 9007199254740991),\n  at REAL NOT NULL,\n  kind TEXT NOT NULL CHECK (kind IN ('join','done','say','hold','resume','read','listen','ignore')),\n  actor_json TEXT COLLATE BINARY,\n  actor_key_json TEXT COLLATE BINARY,\n  reach TEXT CHECK (reach = 'bell'),\n  reply_index INTEGER CHECK (reply_index >= 0 AND reply_index < act_index),\n  payload_json TEXT NOT NULL CHECK (json_valid(payload_json)),\n  CHECK ((actor_json IS NULL) = (actor_key_json IS NULL)),\n  CHECK (kind IN ('hold','resume') OR actor_json IS NOT NULL),\n  CHECK (kind = 'say' OR (reach IS NULL AND reply_index IS NULL))\n);\nCREATE INDEX activity_kind_index ON activities(kind, act_index);\nCREATE INDEX activity_actor_index ON activities(actor_key_json, act_index);\nCREATE INDEX activity_say_actor_index ON activities(actor_key_json, act_index) WHERE kind='say';\nCREATE INDEX activity_say_time ON activities(at, act_index) WHERE kind='say';\nCREATE INDEX activity_bell_actor_time ON activities(actor_key_json, at, act_index) WHERE kind='say' AND reach='bell';\n\nCREATE TABLE receipts (\n  owner_json TEXT COLLATE BINARY NOT NULL,\n  act_index INTEGER NOT NULL CHECK (act_index BETWEEN 0 AND 9007199254740991),\n  at REAL NOT NULL,\n  PRIMARY KEY (owner_json, act_index)\n) WITHOUT ROWID;\nCREATE INDEX receipt_owner_time ON receipts(owner_json, at);\nCREATE TABLE catch_leases (\n  owner_json TEXT COLLATE BINARY PRIMARY KEY NOT NULL,\n  lease_id_json TEXT NOT NULL,\n  heartbeat_at REAL NOT NULL,\n  expires_at REAL NOT NULL CHECK (expires_at >= heartbeat_at),\n  filter_json TEXT CHECK (filter_json IS NULL OR json_valid(filter_json))\n) WITHOUT ROWID;\n\nCREATE TABLE routes (\n  position INTEGER PRIMARY KEY CHECK (position >= 0),\n  participant_key_json TEXT COLLATE BINARY NOT NULL,\n  session_json TEXT COLLATE BINARY NOT NULL,\n  kind TEXT NOT NULL CHECK (kind IN ('opencode-server','codex-queue','claude-native','paseo')),\n  updated_at REAL NOT NULL,\n  payload_json TEXT NOT NULL CHECK (json_valid(payload_json))\n);\nCREATE INDEX route_participant ON routes(participant_key_json, position);\nCREATE INDEX route_session ON routes(session_json, position);\n\nCREATE TABLE participants (\n  name_key_json TEXT COLLATE BINARY PRIMARY KEY NOT NULL,\n  name_json TEXT NOT NULL,\n  first_index INTEGER NOT NULL UNIQUE,\n  joined INTEGER NOT NULL CHECK (joined IN (0,1)),\n  done INTEGER NOT NULL CHECK (done IN (0,1)),\n  say_count INTEGER NOT NULL CHECK (say_count >= 0),\n  last_active_at REAL,\n  last_join_index INTEGER,\n  CHECK (NOT (joined=1 AND done=1))\n) WITHOUT ROWID;\nCREATE TABLE attention (\n  listener_key_json TEXT COLLATE BINARY NOT NULL,\n  target_key_json TEXT COLLATE BINARY NOT NULL,\n  target_json TEXT NOT NULL,\n  kind TEXT NOT NULL CHECK (kind IN ('listen','ignore')),\n  since_index INTEGER NOT NULL,\n  PRIMARY KEY (listener_key_json, target_key_json)\n) WITHOUT ROWID;\nCREATE INDEX attention_target ON attention(target_key_json, kind, listener_key_json);\nCREATE TABLE landed_audience (\n  act_index INTEGER NOT NULL,\n  recipient_key_json TEXT COLLATE BINARY NOT NULL,\n  recipient_order INTEGER NOT NULL CHECK (recipient_order >= 0),\n  route TEXT NOT NULL CHECK (route IN ('mention','reply','attention','bell')),\n  PRIMARY KEY (act_index, recipient_key_json),\n  UNIQUE (act_index, recipient_order)\n) WITHOUT ROWID;\nCREATE INDEX audience_recipient ON landed_audience(recipient_key_json, act_index);";

package/dist/square-sqlite.js

@@ -13,19 +13,11 @@ const V1_SNAPSHOT_COLUMNS = [
     { cid: 1, name: 'revision', type: 'INTEGER', notnull: 1, dflt_value: null, pk: 0, hidden: 0 },
     { cid: 2, name: 'state', type: 'TEXT', notnull: 1, dflt_value: null, pk: 0, hidden: 0 },
 ];
-/**
- * The one recovery command for an owned legacy artifact, with a shell-quoted
- * path. Kept beside framing recognition so the refusal and migration
- * instruction cannot drift apart. This codec stays free of the renderer.
- */
-export function migrationRecoveryCommand(location) {
-    return `square --location '${location.replace(/'/g, `'\\''`)}' migrate`;
-}
 /**
  * Read-only legacy framing: application id, format version, journal mode and the
  * exact owned snapshot schema. It decodes no snapshot payload, writes no pragma
- * and runs no DDL, so ordinary open can establish ownership before offering
- * the migration command. Anything else is unrelated or unsupported, not repaired.
+ * and runs no DDL, so ordinary open can establish ownership before requiring
+ * migration. Anything else is unrelated or unsupported, not repaired.
  */
 export function validateLegacyFraming(database, applicationId, location = '') {
     const identity = database.prepare('SELECT application_id, user_version FROM pragma_application_id, pragma_user_version').get();
@@ -328,7 +320,7 @@ export function validateSqliteHeader(db, location = '') {
     requireFact(identity.application_id === APPLICATION_ID, 'unrelated SQLite database.');
     if (identity.user_version === 1) {
         validateLegacyFraming(db, APPLICATION_ID, location);
-        throw new SquareError('invalid_args', `Square artifact needs migration.\n${migrationRecoveryCommand(location)}`, { reason: 'migration_required' });
+        throw new SquareError('invalid_args', `Square artifact at ${location} needs migration.\nStop sessions using it, back it up, then migrate and verify before restarting.`, { reason: 'migration_required' });
     }
     requireFact(identity.user_version === 2, 'unsupported SQLite format version.');
     const actual = db.prepare("SELECT sql FROM sqlite_schema WHERE name NOT GLOB 'sqlite_*' AND sql IS NOT NULL").all().map(r => normalizedSql(string(r.sql))).sort();

package/dist/square-tools.js

@@ -1,7 +1,7 @@
 import { z } from 'zod/v4';
 import { isSquareError } from './model.js';
 const location = z.string().optional().describe('Path to the .square artifact, relative to the current working directory. Defaults to the configured square.');
-const participant = z.string().optional().describe('Participant name, same as --as. Defaults to the configured participant or the current session’s unambiguous participant.');
+const participant = z.string().optional().describe('Participant name. Defaults to the configured participant or the current session’s unambiguous participant.');
 const activityId = z.string().regex(/^act\/(0|[1-9][0-9]*)$/);
 const stringArray = z.array(z.string());
 function tool(name, description, shape, run) {

package/guides/claude-native.md

@@ -75,7 +75,9 @@ old ends cannot retire that replacement. Unchanged reload preserves epochs.
 ## Body, admission, and presentation
 
 The coordinator uses Square's canonical audience projection and bounded body
-preview. A clipped preview ends with the full `catch --id act/<index>` command.
+preview. Each notification identifies the square, receiving participant and
+activity before its event and body. A clipped preview describes catching that
+activity to read it in full; it never embeds shell commands or tool-call syntax.
 Opaque text correlation resolves through bound memberships and the existing
 attempt ledger, never a path or asserted source from incoming text.
 

package/guides/migration.md

@@ -6,7 +6,8 @@ sparse receipts, catch leases, ordered routes and the small configuration
 facts — in one in-place database.
 
 Existing artifacts are **not** converted automatically. A normal read of a
-version 1 artifact refuses with the exact command to run:
+version 1 artifact refuses with a descriptive offline-migration requirement.
+The CLI adds the concrete recovery command; native tools retain the description:
 
 ```sh
 square --location /path/to/SQUARE.square migrate

package/guides/row-storage-design.md

@@ -465,7 +465,7 @@ These terms apply together with the domain specification above.
 ## Migration protocol
 
 - Only `square --location <path.square> migrate`. No --check, --backup, --force, auto-migrate, bulk mode, separate lock database, sidecar, daemon, or runtime dual reader. An operator can make an offline backup with ordinary tooling; the command does not invent a backup lifecycle.
-- application_id remains 0x53515245; user_version 2 identifies rows. Normal new-format reads/writes refuse version 1 with invalid_args / reason migration_required and a shell-quoted full migration command. build --force does not bypass it. Unknown/unrelated/invalid formats are refused, not repaired.
+- application_id remains 0x53515245; user_version 2 identifies rows. Normal new-format reads/writes refuse version 1 with invalid_args / reason migration_required and descriptive offline-migration guidance. The CLI adds the shell-quoted recovery command; native tool errors do not embed invocation syntax. build --force does not bypass it. Unknown/unrelated/invalid formats are refused, not repaired.
 - `doctor` remains read-only: recognizes legacy v1 and prints the migration recovery command (exit 2); validates v2 fully, including a replay comparison of derived indices. It must not imply that legacy v1 is damaged. Directory/list probing retains omission semantics for unsupported files; no new implicit migration/discovery subsystem.
 - Open existing canonical path create-disabled. A read-only preflight establishes owned known schema/version before any persistent pragma or DDL. Require existing DELETE journal mode, refuse another mode without changing it; the shipped v1 creator/writer already establishes DELETE. Set connection busy_timeout=0 and synchronous=FULL. Acquire BEGIN IMMEDIATE, re-check format/schema under the lock, and validate the full v1 snapshot inside it. If v2 is already present and has valid framing/header, return already-format-2 without changing revision. A second migrator follows this same in-lock check.
 - Use v1 validation retained ONLY in migration (test oracle may also retain it), plus one explicit restriction: non-finite numbers anywhere in a route (including nested extras) are unsupported input, refused before DDL/inserts with the artifact untouched. They are not normally persisted as non-finite values by the v1 JSON.stringify writer; do not add a bespoke overflow-number codec or silently coerce to null. Copy normally persisted authoritative facts losslessly, preserving revision and nextActIndex, activity indices/gaps and optional field distinctions, raw receipt/lease owner keys, route order/duplicates, strings and finite fractional timestamps. Absent routes and [] both become zero rows; empty receipt-owner maps are behaviorless and may become zero receipt rows. Do not canonicalize receipts or add foreign keys that reject accepted v1 facts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.77",
+  "version": "0.3.78",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.77",
+  "version": "0.3.78",
   "description": "Native Claude Code inbox delivery for Square participants",
   "types": "./types.d.ts",
   "author": {

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.77",
+  "version": "0.3.78",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/plugins/pi/square-pi.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { Text } from '@earendil-works/pi-tui';
+import { Container, Markdown, Spacer, Text } from '@earendil-works/pi-tui';
 import { z } from 'zod/v4';
 
 import { createSquareApplication } from '../../dist/square-application.js';
@@ -9,6 +9,7 @@ import { presentPendingAtBoundary, renderPendingAtBoundary } from '../../dist/bo
 import { automaticSessionEnd, automaticSessionStart, operationEnv } from '../../dist/automatic-session.js';
 import { sessionInbox, observeSessionPending } from '../../dist/inbox.js';
 import { previewAttentionBody, renderAttentionDescription, renderAttentionFull } from '../../dist/attention-presentation.js';
+import { formatActivityId } from '../../dist/square-core.js';
 import { createPiReceiver, sendPiMessage } from '../../dist/packages/agent-delivery/src/pi.js';
 
 class PiDeliveryDroppedError extends Error {
@@ -36,15 +37,17 @@ function framePiMessage(content) {
   return `\n${content.replace(/^\n+/, '').replace(/\n+$/, '')}\n`;
 }
 
-/** Renderer-only summary and full text; Pi never sends `details` to the model. */
+/** Renderer-only card facts for Pi and Paseo; 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'),
     actor: note.actor,
     recipient: membership.name,
     route: note.route,
+    act: formatActivityId(note.actIndex),
     preview: previewAttentionBody(note.body),
-    description: renderAttentionDescription({ actor: note.actor, recipient: membership.name, route: note.route }),
+    description: renderAttentionDescription({ actor: note.actor, route: note.route }),
+    body: note.body,
   })));
   if (items.length === 0) return undefined;
   const fullText = pending.flatMap((membership) => membership.notifications.map((note) => renderAttentionFull({
@@ -73,31 +76,67 @@ function fitColumns(text, columns) {
   return `${out}…`;
 }
 
+const fg = (theme, color, text) => theme.fg?.(color, text) ?? text;
+const style = (theme, name) => (text) => theme[name]?.(text) ?? text;
+
+function markdownTheme(theme) {
+  const color = (name) => (text) => fg(theme, name, text);
+  return {
+    heading: color('mdHeading'), link: color('mdLink'), linkUrl: color('mdLinkUrl'), code: color('mdCode'),
+    codeBlock: color('mdCodeBlock'), codeBlockBorder: color('mdCodeBlockBorder'), quote: color('mdQuote'),
+    quoteBorder: color('mdQuoteBorder'), hr: color('mdHr'), listBullet: color('mdListBullet'),
+    bold: style(theme, 'bold'), italic: style(theme, 'italic'), underline: style(theme, 'underline'),
+    strikethrough: style(theme, 'strikethrough'),
+  };
+}
+
+/** One styled line that never exceeds the width; truncated lines stay unstyled so escapes are never cut. */
+function fitLine(parts, width) {
+  const plain = parts.map(([text]) => text).join('');
+  return widthOf(plain) <= width ? parts.map(([text, paint]) => paint(text)).join('') : fitColumns(plain, width);
+}
+
 /**
- * Collapsed: one line naming who reached you and where. Expanded: the complete
- * notification text from renderer details, wrapped by Pi's terminal component.
+ * Collapsed: who reached you and where, then the first line of what they said.
+ * Expanded: each activity as a heading line and its Markdown body; the model's
+ * framing and continuation hints are not for human eyes.
  */
 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 (!Array.isArray(items) || items.length === 0) return undefined;
-  const [first] = items;
-  const tail = ` · ${first.square}${items.length > 1 ? ` +${items.length - 1}` : ''}`;
-  return {
-    invalidate() {},
-    render(width) {
-      const room = Math.max(1, width - outputPad * 2 - 2);
-      // Style only an untruncated line, so escape codes never count toward or get cut by the width.
-      const line = widthOf(first.description + tail) <= room
-        ? `${first.description}${theme.fg('dim', tail)}`
-        : fitColumns(first.description + tail, room);
-      return [`${' '.repeat(outputPad)}${theme.fg('customMessageLabel', '■')} ${line}`];
-    },
-  };
+  if (!Array.isArray(items) || items.length === 0 || items.some((item) => typeof item.body !== 'string')) return undefined;
+  const pad = ' '.repeat(outputPad);
+  const dim = (text) => fg(theme, 'dim', text);
+  if (!expanded) {
+    const [first] = items;
+    const more = items.length > 1 ? ` +${items.length - 1}` : '';
+    // A glance, not a render: drop the commonest inline markers so the line reads as speech.
+    const opening = (first.body.split('\n').find((line) => line.trim() !== '') ?? '')
+      .trim().replace(/^(#{1,6}|>|[-*+])\s+/, '').replace(/\*\*|__|`/g, '');
+    return {
+      invalidate() {},
+      render(width) {
+        const room = Math.max(1, width - outputPad * 2 - 2);
+        return [
+          `${pad}${fg(theme, 'customMessageLabel', '■')} ${fitLine([[first.description, (t) => t], [` · ${first.square} · ${first.recipient}${more}`, dim]], room)}`,
+          ...(opening ? [`${pad}  ${fitLine([[opening, dim]], room)}`] : []),
+        ];
+      },
+    };
+  }
+  const card = new Container();
+  for (const [index, item] of items.entries()) {
+    if (index > 0) card.addChild(new Spacer(1));
+    card.addChild({
+      invalidate() {},
+      render(width) {
+        const room = Math.max(1, width - outputPad * 2 - 2);
+        return [`${pad}${fg(theme, 'customMessageLabel', '●')} ${fitLine([[item.description, (t) => t], [`  ${item.square} · ${item.recipient} · ${item.act}`, dim]], room)}`];
+      },
+    });
+    card.addChild(new Spacer(1));
+    card.addChild(new Markdown(item.body, outputPad + 2, 0, markdownTheme(theme)));
+  }
+  return card;
 }
 
 export default function squarePiExtension(pi) {