@astrosheep/square 0.3.33 → 0.3.35

package/dist/views.js

@@ -1,4 +1,4 @@
-import { extractMentions, formatActivityId, parseActivityId } from './square-core.js';
+import { formatActivityId, parseActivityId } from './square-core.js';
 import { deliveryDelta, directedPeerSays } from './activity-feed.js';
 import { coreActivities, coreParticipants, coreStatus, resolveKnownName } from './decisions.js';
 import { deriveDeliveryModel, isActivitySeen } from './delivery.js';
@@ -7,15 +7,7 @@ import { countSays, currentHold, foldedState, freshWatchLease, inSquareCount, is
 function expose(stored) {
     if (stored.kind === 'read' || stored.actor === undefined)
         throw new Error(`Cannot expose stored activity ${formatActivityId(stored.index)}`);
-    return { id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor, ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}), mentions: stored.kind === 'say' ? extractMentions(stored.body) : [], ...('target' in stored ? { target: stored.target } : {}), ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}) };
-}
-function exposePerceived(stored, viewer, delivery) {
-    const perception = delivery.perceive(stored, viewer);
-    const activity = expose(stored);
-    if (perception === 'full' || activity.body === undefined)
-        return { ...activity, perception };
-    const { body: _body, ...withoutBody } = activity;
-    return { ...withoutBody, perception };
+    return { id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor, ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}), mentions: stored.kind === 'say' ? stored.mentions ?? [] : [], ...('target' in stored ? { target: stored.target } : {}), ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}) };
 }
 function parseRequiredActivityId(id) {
     const index = parseActivityId(id);
@@ -23,12 +15,12 @@ function parseRequiredActivityId(id) {
         throw new SquareError('invalid_args', `Invalid activity id: ${id}`);
     return index;
 }
-function historyOptions(query, viewer) {
+function historyOptions(query) {
     if (query.before !== undefined && query.after !== undefined)
         throw new SquareError('invalid_args', 'History cannot combine before and after cursors');
     const afterIndex = query.after === undefined ? undefined : parseRequiredActivityId(query.after);
     const beforeIndex = query.before === undefined ? undefined : parseRequiredActivityId(query.before);
-    return { ...(query.from === undefined ? {} : { participants: [...query.from] }), ...(query.grep === undefined ? {} : { grep: query.grep }), ...(query.mention === true && viewer !== undefined ? { mention: viewer } : {}), ...(afterIndex === undefined ? {} : { afterIndex }), ...(beforeIndex === undefined ? {} : { beforeIndex }), order: 'asc' };
+    return { ...(query.from === undefined ? {} : { participants: [...query.from] }), ...(query.grep === undefined ? {} : { grep: query.grep }), ...(query.mention === undefined ? {} : { mention: query.mention }), ...(afterIndex === undefined ? {} : { afterIndex }), ...(beforeIndex === undefined ? {} : { beforeIndex }), order: 'asc' };
 }
 function selectHistory(stored, query) {
     let selected = stored.filter((activity) => activity.kind !== 'read');
@@ -67,14 +59,14 @@ function sayNumbers(state) {
     return result;
 }
 export async function history(square, query = {}) { const { state } = await square.artifact.read(); return selectHistory(coreActivities(state, historyOptions(query)), query).map(expose); }
-export async function participantHistory(square, name, query = {}) { const { state } = await square.artifact.read(); const viewer = resolveKnownName(state, name); const delivery = deriveDeliveryModel(state); const effective = query.limit !== undefined ? query : { ...query, limit: 10 }; return selectHistory(coreActivities(state, historyOptions(effective, viewer), delivery), effective).map((activity) => exposePerceived(activity, viewer, delivery)); }
+export async function participantHistory(square, _name, query = {}) { const { state } = await square.artifact.read(); const effective = query.limit !== undefined ? query : { ...query, limit: 10 }; return selectHistory(coreActivities(state, historyOptions(effective)), effective).map(expose); }
 export async function resolveParticipant(square, name) { const { state } = await square.artifact.read(); return { name: resolveKnownName(state, name), roster: rosterNames(state) }; }
 export async function currentParticipant(square, name) { const { state } = await square.artifact.read(); const known = resolveRosterName(state, name); return known !== undefined && isCurrentlyJoined(state.acts, known) ? known : undefined; }
 export async function participants(square) { const { state } = await square.artifact.read(); return statuses(square, state); }
 export async function snapshot(square) { const { state } = await square.artifact.read(); const folded = foldedState(state); return { context: [...state.preamble, ...state.warmup].join('\n'), actCount: state.acts.filter((activity) => activity.kind !== 'read').length, hardCap: state.hardCap, ...(state.throttlePerMinute === undefined ? {} : { throttlePerMinute: state.throttlePerMinute }), held: folded.hold.active && folded.hold.actor !== undefined ? { by: folded.hold.actor, ...(folded.hold.reason === undefined ? {} : { reason: folded.hold.reason }) } : null, participants: statuses(square, state), delivered(name, id) { return isActivitySeen(state, name, parseRequiredActivityId(id)); } }; }
 export async function activityPresentation(square, name) { const { state } = await square.artifact.read(); const known = resolveKnownName(state, name); const delivery = deriveDeliveryModel(state); const delta = deliveryDelta(state, known, delivery); const hold = currentHold(state.acts); return { name: known, roster: rosterNames(state), pendingPublic: directedPeerSays(state, delta, known, delivery), pendingRoomChanges: [], activities: state.acts, state, participantCount: inSquareCount(state), held: hold.active, ...(hold.reason === undefined ? {} : { holdReason: hold.reason }), ownActivityCount: countSays(state.acts, known), hardCap: state.hardCap }; }
 export async function entryPresentation(square, name, lastN = 10) { const { state } = await square.artifact.read(); const known = resolveRosterName(state, name) ?? name; const publicActivities = state.acts.filter((activity) => activity.kind === 'say' || activity.kind === 'done'); return { joined: isCurrentlyJoined(state.acts, known), scene: state.warmup.join('\n').trim(), context: state.preamble.join('\n').trim(), joinContext: (state.preamble.at(-1) === '---' ? state.preamble.slice(0, -1) : state.preamble).join('\n').trim(), recentActivities: lastN === null ? publicActivities : publicActivities.slice(-lastN), state, sayNumbers: sayNumbers(state), participantCount: inSquareCount(state) }; }
-export async function historyPresentation(square, options) { const { state } = await square.artifact.read(); const delivery = deriveDeliveryModel(state); return { activities: coreActivities(state, options, delivery).map((activity) => ({ ...activity, perception: options.viewer === undefined ? 'full' : delivery.perceive(activity, options.viewer) })), sayNumbers: sayNumbers(state), presenceAnchors: anchors(state, delivery), participantCount: inSquareCount(state) }; }
+export async function historyPresentation(square, options) { const { state } = await square.artifact.read(); const delivery = deriveDeliveryModel(state); return { activities: coreActivities(state, options, delivery), sayNumbers: sayNumbers(state), presenceAnchors: anchors(state, delivery), participantCount: inSquareCount(state) }; }
 export async function participantsPresentation(square) { const { state } = await square.artifact.read(); const delivery = deriveDeliveryModel(state); return coreParticipants(state, square.clock(), delivery); }
 export async function listPresentation(square) { const { state } = await square.artifact.read(); return { context: state.preamble, participants: foldedState(state).participants.filter((participant) => participant.joined).sort((left, right) => (right.lastActiveAt ?? -Infinity) - (left.lastActiveAt ?? -Infinity) || left.name.localeCompare(right.name)).map((participant) => participant.name), activities: state.acts.filter((activity) => activity.kind === 'say').length }; }
 export async function statusPresentation(square) { const { state } = await square.artifact.read(); const delivery = deriveDeliveryModel(state); const status = coreStatus(state, square.clock(), delivery); return { state, status, ...(status.latestAct?.kind === 'say' ? { latestActNumber: countSays(state.acts, status.latestAct.actor) } : {}) }; }
@@ -83,8 +75,42 @@ export async function eventPresentation(square, id) { const { state } = await sq
 export async function watchPresentation(square, name) { const { state } = await square.artifact.read(); const known = resolveKnownName(state, name); const now = square.clock(); const terminal = watchTerminalStatus(state, known); const delivery = deriveDeliveryModel(state); return { activities: state.acts, state, participantCount: inSquareCount(state), presence: { participants: coreParticipants(state, now, delivery), now }, ...(terminal === undefined ? {} : { terminalStatus: terminal }) }; }
 export async function inboxProjection(square, name, _sessionId) { const { state } = await square.artifact.read(); const delivery = deriveDeliveryModel(state); const known = delivery.knownParticipant(name); if (known === undefined || !delivery.joinedRecipients().some((recipient) => nameKey(recipient) === nameKey(known)))
     return { name, joined: false, notifications: [] }; const lease = freshWatchLease(state, known, square.clock()); return { name: known, joined: true, notifications: delivery.pendingFor(known).map(({ item, route }) => ({ actIndex: item.index, actor: item.actor, at: item.at, route, body: item.body })), ...(lease === undefined ? {} : { catchLease: lease }) }; }
-export async function streamProjection(square, cursor, recipient) { const artifact = 'artifact' in square ? square.artifact : square.cell; const { state } = await artifact.read(); const delivery = recipient === undefined ? undefined : deriveDeliveryModel(state); return { activities: state.acts.filter((activity) => activity.index > cursor).flatMap((activity) => { if (delivery === undefined || recipient === undefined)
-        return [{ activity }]; const notification = delivery.plan(activity).find((candidate) => nameKey(candidate.recipient) === nameKey(recipient)); return notification === undefined ? [] : [{ activity, route: notification.route }]; }), cursor: Math.max(cursor, ...state.acts.map((activity) => activity.index)) }; }
+const STREAM_BATCH_MAX = 100;
+function projectStreamActivities(state, activities, recipient) {
+    const delivery = recipient === undefined ? undefined : deriveDeliveryModel(state);
+    return activities.flatMap((activity) => {
+        if (delivery === undefined || recipient === undefined)
+            return [{ activity }];
+        const notification = delivery.plan(activity).find((candidate) => nameKey(candidate.recipient) === nameKey(recipient));
+        return notification === undefined ? [] : [{ activity, route: notification.route }];
+    });
+}
+function selectStreamTail(activities, last) {
+    if (!Number.isSafeInteger(last) || last < 0 || last > STREAM_BATCH_MAX) {
+        throw new SquareError('invalid_args', `Invalid stream tail: expected a non-negative safe integer no greater than ${STREAM_BATCH_MAX}.`);
+    }
+    return last === 0 ? [] : activities.slice(-last);
+}
+export async function streamProjection(square, cursor, recipient) {
+    const artifact = 'artifact' in square ? square.artifact : square.cell;
+    const { state } = await artifact.read();
+    const pending = state.acts.filter((activity) => activity.index > cursor);
+    const batch = pending.slice(0, STREAM_BATCH_MAX);
+    return {
+        activities: projectStreamActivities(state, batch, recipient),
+        cursor: batch.at(-1)?.index ?? cursor,
+        hasMore: pending.length > batch.length,
+    };
+}
+export async function streamTailProjection(square, last = 10, recipient) {
+    const artifact = 'artifact' in square ? square.artifact : square.cell;
+    const { state } = await artifact.read();
+    return {
+        activities: selectStreamTail(projectStreamActivities(state, state.acts, recipient), last),
+        cursor: state.acts.at(-1)?.index ?? -1,
+        hasMore: false,
+    };
+}
 export async function notificationForAct(square, actIndex) { const { state } = await square.artifact.read(); const activity = state.acts.find((candidate) => candidate.index === actIndex); return activity === undefined ? [] : deriveDeliveryModel(state).plan(activity); }
 export function pendingDeliveriesFromState(state, delivery = deriveDeliveryModel(state)) { return delivery.joinedRecipients().map((recipient) => ({ recipient, notifications: delivery.pendingFor(recipient) })); }
 export async function pendingDeliveries(square) { const { state } = await square.artifact.read(); return pendingDeliveriesFromState(state); }

package/dist/wake-sink.d.ts

@@ -8,5 +8,7 @@ export declare class PaseoWakeSendError extends Error {
     constructor(message: string, kind: PaseoWakeFailureKind);
 }
 export declare function sendPaseoWake({ agentId, prompt }: PaseoWakeRequest, opts?: {
+    args?: string[];
+    bin?: string;
     timeoutMs?: number;
 }): void;

package/dist/wake-sink.js

@@ -31,8 +31,17 @@ function classifyCommandFailure(code, message) {
 function redactUriPassword(value) {
     return value.replace(/([?&]password=)[^&\s]+/gi, '$1[redacted]');
 }
+function configuredArguments(name) {
+    try {
+        const parsed = JSON.parse(process.env[name] ?? '[]');
+        return Array.isArray(parsed) && parsed.every((item) => typeof item === 'string') ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
 export function sendPaseoWake({ agentId, prompt }, opts = {}) {
-    const result = spawnSync(process.env.SQUARE_PASEO_BIN || 'paseo', ['send', agentId, '--prompt', prompt, '--no-wait', '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: opts.timeoutMs ?? 5000, env: process.env });
+    const result = spawnSync(opts.bin ?? process.env.SQUARE_PASEO_BIN ?? 'paseo', [...(opts.args ?? configuredArguments('SQUARE_PASEO_BIN_ARGS')), 'send', agentId, '--prompt', prompt, '--no-wait', '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: opts.timeoutMs ?? 5000, env: process.env });
     if (result.error) {
         const code = result.error.code;
         const kind = code === 'ENOENT' || code === 'ECONNREFUSED' ? 'transient' : 'unknown';

package/dist/watch.js

@@ -6,7 +6,7 @@ import { closeOpenSquare } from './open-square.js';
 import { openParticipant } from './square-wiring.js';
 import { resolveParticipant, watchPresentation } from './views.js';
 import { acquireWatchLease, ownsWatchLease, pulseWatchLease, releaseWatchLease } from './wakes.js';
-import { renderWatchForceTakeover, renderWatchAlreadyActive, renderWatchOutput, renderWatchReplaced, renderWatchStatus, participantCommandPrefix, withPathOutput, } from './presentation.js';
+import { renderWatchForceTakeover, renderWatchAlreadyActive, renderWatchReplaceMissing, renderWatchOutput, renderWatchReplaced, renderWatchStatus, participantCommandPrefix, withPathOutput, } from './presentation.js';
 import { hasAutomaticDeliveryIdentity } from './registry.js';
 import { parseActivityId } from './square-core.js';
 function watchStatusExitCode(status) {
@@ -36,18 +36,31 @@ function watchOutputResult(squarePath, presentation, name, caught, opts = {}) {
             viewer: name,
             showCatchHint: !hasAutomaticDeliveryIdentity(),
             perceptions,
-        }),
+        }) + (caught.remaining > 0
+            ? `\n○ ${caught.remaining} matching ${caught.remaining === 1 ? 'activity remains' : 'activities remain'}\n» ${catchContinuationCommand(squarePath, name, opts)}`
+            : ''),
+        remaining: caught.remaining,
         ...(opts.status ? { status: opts.status } : {}),
     };
 }
-function writeWatchOutput(squarePath, name, presentation, stdout, status, idleMs) {
+function catchContinuationCommand(squarePath, name, opts) {
+    const args = ['--now'];
+    if (opts.participants !== undefined && opts.participants.length > 0)
+        args.push('--from', opts.participants.join(','));
+    if (opts.mention !== undefined)
+        args.push('--mention');
+    if (opts.limit !== undefined)
+        args.push('--limit', String(opts.limit));
+    return `${participantCommandPrefix(squarePath, name)} catch ${args.join(' ')}`;
+}
+function writeWatchOutput(squarePath, name, presentation, stdout, remaining, status, idleMs) {
     const headerOpts = { participantCount: presentation.participantCount };
     const showCatchHint = !hasAutomaticDeliveryIdentity();
     if (status) {
         process.stdout.write(withPathOutput(squarePath, [renderWatchStatus({ status, squarePath, name, idleMs, presence: presentation.presence, showCatchHint }), stdout.trimEnd()].filter(Boolean).join('\n\n').trimEnd(), headerOpts));
         return;
     }
-    const fallback = showCatchHint
+    const fallback = showCatchHint && remaining === 0
         ? `» ${participantCommandPrefix(squarePath, name)} catch --idle 30m\n  stay available for new activity`
         : '';
     process.stdout.write(withPathOutput(squarePath, [stdout.trimEnd(), fallback].filter(Boolean).join('\n\n').trimEnd(), headerOpts));
@@ -68,7 +81,7 @@ function writeWatchReplaced(squarePath, name, presentation) {
 async function finishWatchResult(square, squarePath, name, result, leaseId, idleMs) {
     if (result.type === 'output') {
         await endWatch(square, name, leaseId);
-        writeWatchOutput(squarePath, name, await watchPresentation(square, name), result.stdout, result.status);
+        writeWatchOutput(squarePath, name, await watchPresentation(square, name), result.stdout, result.remaining, result.status);
         process.exitCode = watchStatusExitCode(result.status);
         return true;
     }
@@ -115,11 +128,12 @@ async function cmdWatchNow(squarePath, name, opts) {
         const caught = await facade.participant.catch({
             ...(opts.participants === undefined ? {} : { from: opts.participants }),
             ...(opts.mention === undefined ? {} : { mention: true }),
+            ...(opts.limit === undefined ? {} : { limit: opts.limit }),
         });
         const presentation = await watchPresentation(square, name);
         const status = presentation.terminalStatus;
         const result = caught.activities.length > 0
-            ? watchOutputResult(squarePath, presentation, name, caught, { mention: opts.mention, ...(status ? { status } : {}) })
+            ? watchOutputResult(squarePath, presentation, name, caught, { mention: opts.mention, participants: opts.participants, limit: opts.limit, ...(status ? { status } : {}) })
             : { type: 'terminal', status: status ?? 'empty-now' };
         await finishWatchResult(square, squarePath, name, result, undefined);
         return caught.activities.length > 0;
@@ -162,9 +176,11 @@ export async function cmdWatch(squarePath, name, opts) {
     let staleSince = nowMs();
     let currentLeaseId = start.leaseId;
     let nextHeartbeatAt = start.heartbeatAt + WATCH_HEARTBEAT_MS;
-    if (start.replaced) {
+    if (opts.replace) {
         const presentation = await watchPresentation(square, name);
-        process.stdout.write(withPathOutput(squarePath, renderWatchForceTakeover({ squarePath, name }), { participantCount: presentation.participantCount }));
+        process.stdout.write(withPathOutput(squarePath, start.replaced
+            ? renderWatchForceTakeover({ squarePath, name })
+            : renderWatchReplaceMissing({ squarePath, name }), { participantCount: presentation.participantCount }));
     }
     const idleMs = opts.idleMs ?? STALE_MS;
     const removeInterruptHandler = installWatchInterruptHandler(square, squarePath, name, () => currentLeaseId);
@@ -180,9 +196,10 @@ export async function cmdWatch(squarePath, name, opts) {
                 const caught = await facade.participant.catch({
                     ...(opts.participants === undefined ? {} : { from: opts.participants }),
                     ...(opts.mention === undefined ? {} : { mention: true }),
+                    ...(opts.limit === undefined ? {} : { limit: opts.limit }),
                 });
                 if (caught.activities.length > 0) {
-                    result = watchOutputResult(squarePath, await watchPresentation(square, name), name, caught, { mention: opts.mention });
+                    result = watchOutputResult(squarePath, await watchPresentation(square, name), name, caught, { mention: opts.mention, participants: opts.participants, limit: opts.limit });
                 }
             }
             if (await finishWatchResult(square, squarePath, name, result, currentLeaseId)) {

package/extensions/square-pi.js

@@ -43,6 +43,7 @@ export default function squarePiExtension(pi) {
   let settledWaiters = [];
   const handledPending = new Set();
   let retryAfterChange = false;
+  let retryWait;
   const present = (deliver, signal) => sessionId === undefined ? undefined : presentPendingAtBoundary(sessionId, deliver, undefined, undefined, signal);
 
   const presentAtBoundary = (deliver) => {
@@ -88,23 +89,43 @@ export default function squarePiExtension(pi) {
   });
 
   const wake = async (piContext, token, signal) => {
+    const armDeferredRetry = () => {
+      const controller = new AbortController();
+      let resolveArmed;
+      const armed = new Promise((resolve) => { resolveArmed = resolve; });
+      const abort = () => controller.abort();
+      signal.addEventListener('abort', abort, { once: true });
+      const pending = waitForSessionPending(sessionId, 30_000, {
+        signal: controller.signal,
+        excludeKeys: handledPending,
+        skipImmediate: true,
+        onChangeArmed: resolveArmed,
+      }).catch(() => {
+        resolveArmed(false);
+        return [];
+      }).finally(() => signal.removeEventListener('abort', abort));
+      return { armed, pending, cancel: () => controller.abort() };
+    };
+
     while (sessionId !== undefined && token === generation && !signal.aborted) {
       if ((await sessionBindings(sessionId)).length === 0) {
         await pause(signal, 1_000);
         continue;
       }
       const deferredRetry = retryAfterChange;
-      const pending = await waitForSessionPending(sessionId, 30_000, {
-        signal,
-        excludeKeys: handledPending,
-        skipImmediate: deferredRetry,
-      });
+      const pending = deferredRetry && retryWait !== undefined
+        ? await retryWait
+        : await waitForSessionPending(sessionId, 30_000, { signal, excludeKeys: handledPending });
       if (sessionId === undefined || token !== generation || signal.aborted) return;
       if (pending.length === 0) {
-        if (deferredRetry) retryAfterChange = false;
+        if (deferredRetry) {
+          retryAfterChange = false;
+          retryWait = undefined;
+        }
         continue;
       }
       retryAfterChange = false;
+      retryWait = undefined;
       if (!piContext.isIdle()) {
         const serial = settledSerial;
         await waitForSettled(serial, signal);
@@ -113,6 +134,14 @@ export default function squarePiExtension(pi) {
       if (presenting) continue;
       const keys = inboxKeys(pending);
       presenting = true;
+      const deferred = armDeferredRetry();
+      const retryArmed = await deferred.armed;
+      if (!retryArmed) {
+        deferred.cancel();
+        presenting = false;
+        continue;
+      }
+      let keepDeferred = false;
       try {
         const delivered = await presentPendingAtBoundary(
           sessionId,
@@ -149,9 +178,12 @@ export default function squarePiExtension(pi) {
           for (const key of keys) handledPending.add(key);
         }
       } catch {
-        // Leave pending evidence untouched so the next state change can retry.
+        // The next state edge is already being observed before native injection starts.
         retryAfterChange = true;
+        retryWait = deferred.pending;
+        keepDeferred = true;
       } finally {
+        if (!keepDeferred) deferred.cancel();
         presenting = false;
       }
     }
@@ -162,6 +194,7 @@ export default function squarePiExtension(pi) {
     stopWatcher();
     handledPending.clear();
     retryAfterChange = false;
+    retryWait = undefined;
     sessionId = ctx.sessionManager.getSessionId();
     sessionCwd = ctx.cwd || process.cwd();
     previousSessionId = process.env.SQUARE_PI_SESSION_ID;
@@ -208,5 +241,6 @@ export default function squarePiExtension(pi) {
     sessionCwd = undefined;
     joiningContext = undefined;
     presenting = false;
+    retryWait = undefined;
   });
 }

package/package.json

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

package/skills/brainstorm/SKILL.md

@@ -40,7 +40,7 @@ First action: enter the square. Read the context, warmup, and recent activity pr
 square --location <square> --as <name> join
 
 Then follow the Happy Path from the join output. Core commands:
-square --location <square> --as <name> express - <<'EOF'
+square --location <square> --as <name> express --no-mention - <<'EOF'
 ...
 EOF
 square --location <square> --as <name> catch --mention --idle 10m
@@ -55,7 +55,7 @@ EOF
 
 For complete history, follow the activity-id continuation commands printed by `history`.
 
-Every activity must address at least one participant with @name. Mentioned participants perceive the full body; others perceive only directed presence. Use `--bell` only when every participant needs the activity — everyone catching with `--mention` will receive it. Precise history queries may still read original archive bodies.
+Every activity that needs a specific listener uses `--mention <name>`; repeat the flag for multiple participants. Mentioned participants perceive the full body; others perceive only directed presence. Use `--no-mention` for a bare activity and `--bell` only when every participant needs the activity. An `@name` in the body is ordinary Markdown. Precise history queries may still read original archive bodies.
 
 If an activity is refused because something happened while the participant was not looking, run `square --location <square> --as <name> catch --now`, take it in, then express again. `catch --now` catches up without waiting.
 ```
@@ -68,8 +68,8 @@ If you or the human want to participate, choose a participant name and use the p
 
 ```bash
 square --location <square> --as <name> join
-square --location <square> --as <name> express - <<'EOF'
-@<participant-name> your view
+square --location <square> --as <name> express --mention <participant-name> - <<'EOF'
+your view
 EOF
 square --location <square> --as <name> catch --idle 10m
 square --location <square> --as <name> done - <<'EOF'
@@ -87,9 +87,11 @@ square --location <square> history --from <name>
 square --location <square> status
 ```
 
+History shows one result in full and previews multiple results. `--no-truncate` shows every original body.
+
 `history` reads the archive without advancing participant presence. `status` shows active/done participants, activity counts, cap/throttle, hold state, and latest ambient activity.
 
-Every activity must contain `@name`; use `--bell` only for activity that every participant needs.
+Every addressed activity must use `--mention <name>`; use `--no-mention` for a bare activity and `--bell` only for activity that every participant needs.
 
 ## Human Direction
 
@@ -117,7 +119,7 @@ While held, participant expression and catch pause. Join, done, status, and hist
 When participants are done, collect the public activities:
 
 ```bash
-square --location <square> history --no-truncate      # expand preview bodies
+square --location <square> history --no-truncate      # show every original body
 square --location <square> status
 ```
 

package/skills/square/SKILL.md

@@ -21,7 +21,7 @@ leave for good  : done   (permanent — not the end of a round)
 
 ```bash
 square --location .square/PUBLIC.square --as <name> catch --now
-square --location .square/PUBLIC.square --as <name> express "@alice your thought"
+square --location .square/PUBLIC.square --as <name> express --mention alice "your thought"
 ```
 
 For any other square, find it, then `join` it once (`ls` is short for `list`; `--depth N` widens the search):
@@ -46,22 +46,22 @@ square --location <square> --as <name> status
 Everything you land is one activity — pure speech, pure action, or both. In the square, `*asterisks*` are your body: gesture, posture, expression, movement. **Always give speech a body.** Words with no asterisks land as you standing motionless with a blank face; an action lands as hard as speech and often says it faster.
 
 ```bash
-square --location <square> --as <name> express "@alice I disagree — the cache is the wrong layer for this."
-square --location <square> --as <name> express "*nods slowly to @bob*"
-square --location <square> --as <name> express "*stands* @alice, fine. I'll take the migration."
+square --location <square> --as <name> express --mention alice "I disagree — the cache is the wrong layer for this."
+square --location <square> --as <name> express --mention bob "*nods slowly*"
+square --location <square> --as <name> express --mention alice "*stands* Fine. I'll take the migration."
 ```
 
 For a longer activity, use stdin:
 
 ```bash
-square --location <square> --as <name> express - <<'EOF'
+square --location <square> --as <name> express --mention bob - <<'EOF'
 *drops a rough sketch onto the table*
 
-The ownership boundary belongs here. @bob, does this match your read?
+The ownership boundary belongs here. Does this match your read?
 EOF
 ```
 
-**Addressing.** Normally address whoever needs the activity with `@name`: mentioned participants hear the full body even when they are not listening, and everyone else sees you walk over to them. A bare activity (no mention) lands in history whether or not anyone is listening; `listen` only opts a participant into future bare delivery. Use `--bell` only when every participant needs it. Addressing is not a secrecy boundary — `history` is a read-only archive with stable activity-id cursors.
+**Addressing.** Use `--mention <name>` (repeatable) to address participants; they hear the full body even when they are not listening, and everyone else sees you walk over to them. Use `--no-mention` to land a bare activity; `listen` opts a participant into future bare delivery. Use `--bell` only when every participant needs it. An `@name` in the body is ordinary Markdown and does not address anyone. Addressing is not a secrecy boundary — `history` is a read-only archive with stable activity-id cursors.
 
 **Discipline.** Every activity counts against your cap and the square's throttle, so make each one worth landing. Keep private progress and tool chatter out — express only when another participant needs the thought, question, or decision.
 
@@ -78,7 +78,7 @@ square --location <square> --as <name> catch --now --mention       # take in pen
 square --location <square> --as <name> catch --now --from <names>  # take in pending activity from named participants
 ```
 
-Every catch needs exactly one mode: `--now` or `--idle <duration>`. `--mention` and `--from` filter either mode; they do not replace it. Waiting with `catch --idle` is the normal way to stay present between expressions — `join` prints the exact command to keep open. Do not build a polling loop.
+Every catch needs exactly one mode: `--now` or `--idle <duration>`. `--mention` and `--from` filter either mode; they do not replace it. Each catch takes one bounded page: `--limit` defaults to 10 and accepts at most 100, while anything beyond that page stays unread. Waiting with `catch --idle` is the normal way to stay present between expressions — `join` prints the exact command to keep open. Do not build a polling loop.
 
 ## Listen
 
@@ -101,11 +101,11 @@ square history --limit 5               # most recent 5, oldest to newest
 square history --before act/12 --limit 5 # the page before act/12
 square history --after act/12 --limit 5  # the page after act/12
 square history --limit 5 --order desc  # newest first
-square history --no-truncate           # expand preview bodies
+square history --no-truncate           # show every original body
 square history --grep 'term'           # search
 ```
 
-See `square history --help` for advanced usage. Never read or parse the binary Square artifact directly. Bodies are previews by default; follow the printed activity-id command to continue page by page.
+See `square history --help` for advanced usage. Never read or parse the binary Square artifact directly. One result shows its full body; multiple results use previews. `--no-truncate` shows every original body. Follow the printed activity-id command to continue page by page.
 
 ## Hold