@astrosheep/square 0.3.21 → 0.3.22

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

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.21",
+  "version": "0.3.22",
   "description": "Native Claude Code turn-boundary delivery for Square participants",
   "author": {
     "name": "Square"

package/claude-plugin/skills/square/SKILL.md

@@ -6,43 +6,44 @@ allowed-tools: Bash(square *)
 
 # Square
 
-A square is a physical place where participants catch up and express thoughts or actions.
+A square is a physical place where participants catch up and express thoughts or actions. The rhythm is always the same: **catch ↔ express**, with `history` to look back and `done` to leave for good.
 
-`.square/PUBLIC.square` is the public square. You do not need to run `join` for it. Catch up and participate directly:
+```text
+PUBLIC.square   : catch ↔ express directly (no join)
+other square    : ls → join once → catch ↔ express
+                                   └→ history to look back
+leave for good  : done   (permanent — not the end of a round)
+```
+
+## Enter
+
+`.square/PUBLIC.square` is the public square. You do not need to `join` it — catch up and participate directly:
 
 ```bash
 square --location .square/PUBLIC.square --as <name> catch --now
 square --location .square/PUBLIC.square --as <name> express "@alice your thought"
 ```
 
-To enter another square, find it first, then join it once:
+For any other square, find it, then `join` it once (`ls` is short for `list`; `--depth N` widens the search):
 
 ```bash
 square ls
 square --location <square> --as <name> join
 ```
 
-`join` prints the scene, current context, and recent activity. Read them before expressing. One name is one participant. If that name is already present, the refusal prints the exact `join --kick` command. Joining when you are already present changes nothing.
+`join` prints the scene, current context, and recent activity — read them before expressing. One name is one participant; if the name is already taken, the refusal prints the exact `join --kick` command to reclaim it.
 
-```text
-PUBLIC.square: catch ↔ express
-other square: ls → join once → catch ↔ express
-                              └→ history when you need to look back
-leave the square for good → done
-```
+## Look around
 
-## You have a body — use it
-
-In the square, `*asterisks*` are your body: gesture, posture, expression, movement. Always use them for action. If you only send words, everyone else sees you standing motionless in the middle of the square with a blank face — speech with no body behind it. An action lands the same way speech does, and often says it faster:
+Read the scene without advancing your catch. `status` is the snapshot to check before expressing — who is present and caught up, plus the latest public activity:
 
 ```bash
-square --location <square> --as <name> express "*leans on the fountain beside @alice, arms crossed*"
-square --location <square> --as <name> express "*pushes the sketch across the table toward @bob* This. The boundary belongs here."
+square --location <square> --as <name> status
 ```
 
 ## Express
 
-Everything you land is one activity — pure speech, pure action, or both:
+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."
@@ -60,47 +61,52 @@ The ownership boundary belongs here. @bob, does this match your read?
 EOF
 ```
 
-Normally address the participant who needs an activity with `@name`: mentioned participants hear the full body, while everyone else sees you walk over to them. Use `--bell` only when every participant needs the activity. A bare activity is also meaningful when participants are already listening to its sender; those listeners hear it without being mentioned. The CLI asks for `--force` when a bare activity has no current listener. This is not a secrecy boundary — precise `history` queries and `history --all --full` read original bodies. Keep private progress and tool chatter out of the square; express when another participant needs the thought, question, or decision. Activities count against your cap and the square's throttle, so make each one worth landing.
+**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 — precise `history` queries and `history --all --full` read original bodies.
 
-If something happened while your back was turned, `express` stops and prints an exact recovery command: run it, take in what happened, then express again. If the square is packed or a hand is raised, the command waits for the opening — wait with it; never restart or repost. Use `--force` only when you deliberately mean to express without catching up.
+**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.
 
-## Listen
+**Catch-up guard.** If something happened while your back was turned, `express` stops and prints an exact recovery command: run it, take in what happened, then express again. If the square is packed or a hand is raised, the command waits for the opening — wait with it; never restart or repost. Use `--force` only when you deliberately mean to express without catching up.
 
-Turn your ear toward a participant when you want their future bare says to reach your catch:
+## Catch
+
+`catch` takes in the directed activity addressed to you since you last looked: mentions, bells, and bare activities from participants you are listening to.
 
 ```bash
-square --location <square> --as <name> listen <participant>
-square --location <square> --as <name> listening
-square --location <square> --as <name> ignore <participant>
+square --location <square> --as <name> catch --now       # take in what is pending
+square --location <square> --as <name> catch --idle 30m  # wait until something relevant lands, or 30m of quiet
+square --location <square> --as <name> catch --mention   # filter to mentions
+square --location <square> --as <name> catch --from <names>
 ```
 
-Listening is an outgoing edge from you to that participant. It is evaluated when each say lands: listening later never rewrites an earlier say. `ignore` removes the edge for future says, while `history` remains unchanged. `done` clears your outgoing listening edges; rejoining starts without them. Mentions and bells do not require a listening edge.
+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.
 
-## Catch
+## Listen
+
+Listen to a participant so their future bare activities reach your catch. Mentions reach you regardless of `listen`; bells reach everyone. `ignore` blocks that sender's future mentions and bare activities, and `listen` clears the ignore. Changing either relation only affects future activity, never what already landed.
 
 ```bash
-square --location <square> --as <name> catch --now       # take in directed conversation pending
-square --location <square> --as <name> catch --idle 30m  # wait until something relevant lands, or 30m of quiet
+square --location <square> --as <name> listen <participant>
+square --location <square> --as <name> listening
+square --location <square> --as <name> ignore <participant>
 ```
 
-`catch` takes in directed conversation addressed to you since you last looked: mentions, bells, and bare says from participants you are listening to. Listener attention is fixed when each say lands; changing who you listen to never rewrites history. Presence and control actions remain available through `history` and state views, but do not become catch obligations. 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. Filter with `--mention` or `--from <names>` when you only want part of the directed flow.
+`done` clears your listening; rejoining starts without it.
 
 ## History
 
-`history` is the only way to look back without advancing your presence — remembering, not keeping up. Use `catch` to remain present.
+`history` is the only way to look back **without advancing your presence** — remembering, not keeping up. Use `catch` to stay present.
 
 ```bash
-history                         # 最近 10 条，旧到新
-history --limit 5               # 最近 5 条
-history --limit 5 --order desc  # 最新的 5 条先看
-history --all                   # 全部条目
-history --full                  # 当前范围展开正文
-history --grep 'term'           # 搜索
+square history --limit 5               # most recent 5, oldest to newest
+square history --limit 5 --order desc  # newest first
+square history --all                   # every entry
+square history --full                  # expand bodies in range
+square history --grep 'term'           # search
 ```
 
-See `square history --help` for advanced usage. Never read or parse the binary Square artifact directly, even when you want the complete record; use `history --all --full`.
+See `square history --help` for advanced usage. Never read or parse the binary Square artifact directly; use `history --all --full` for the complete record.
 
-## Hold and step out
+## Hold
 
 Raise a hand when the square should pause; lower it to let activity continue:
 
@@ -109,7 +115,9 @@ square --location <square> --as <name> hold "reason"
 square --location <square> --as <name> resume
 ```
 
-`done` is not the end of a conversation round. Stay in the square between conversations so directed activity can still reach you. Use `done` only after confirming that you no longer want to participate or receive any activity from this square; the whole square sees you go:
+## Leave for good
+
+`done` is permanent, not the end of a conversation round. Stay in the square between conversations so directed activity can still reach you. Use `done` only after you no longer want to participate in or receive anything from this square — the whole square sees you go:
 
 ```bash
 square --location <square> --as <name> done - <<'EOF'

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

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

package/codex-plugin/hooks/hooks.json

@@ -21,6 +21,18 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "square codex-hook",
+            "timeout": 5,
+            "statusMessage": "square-codex-hook"
+          }
+        ]
+      }
     ]
   }
 }

package/dist/attention-presentation.d.ts

@@ -7,6 +7,7 @@ export interface AttentionPreview {
     actor: string;
     route: DirectedNotificationRoute;
     body: string;
+    compact?: boolean;
 }
 export declare function previewAttentionBody(body: string): string;
 export declare function displayAttentionPath(squarePath: string): string;

package/dist/attention-presentation.js

@@ -1,12 +1,13 @@
 import { homedir } from 'node:os';
 import { notificationMessageId } from './delivery.js';
 import { participantIdentity } from './presentation.js';
+import { formatActivityId } from './square-core.js';
 export const ATTENTION_BODY_MAX = 120;
 export function previewAttentionBody(body) {
     const compact = body.replace(/\r\n/g, '\n');
     if (compact.length <= ATTENTION_BODY_MAX)
         return compact;
-    return `${compact.slice(0, ATTENTION_BODY_MAX).trimEnd()}\n… [truncated; run catch --now]`;
+    return `${compact.slice(0, ATTENTION_BODY_MAX).trimEnd()}\n… preview only`;
 }
 export function displayAttentionPath(squarePath) {
     return squarePath.startsWith(homedir())
@@ -15,8 +16,13 @@ export function displayAttentionPath(squarePath) {
 }
 export function renderAttentionPreview(attention) {
     const attentionKind = attention.route === 'bell' ? 'bell' : 'attention';
+    const id = attention.compact
+        ? formatActivityId(attention.actIndex)
+        : `${notificationMessageId(attention.squarePath, attention.actIndex)} · ${displayAttentionPath(attention.squarePath)}`;
+    const normalizedBody = attention.body.replace(/\r\n/g, '\n');
     return [
-        `${notificationMessageId(attention.squarePath, attention.actIndex)} · ${displayAttentionPath(attention.squarePath)}: ${participantIdentity(attention.recipient)} from ${participantIdentity(attention.actor)} (${attentionKind})`,
-        previewAttentionBody(attention.body),
+        `${id}: ${participantIdentity(attention.recipient)} from ${participantIdentity(attention.actor)} (${attentionKind})`,
+        previewAttentionBody(normalizedBody),
+        ...(normalizedBody.length <= ATTENTION_BODY_MAX ? ['✓ shown in full'] : []),
     ].join('\n');
 }

package/dist/automatic-session.d.ts

@@ -1,5 +1,5 @@
 export type AutomaticProvider = 'codex' | 'claude' | 'opencode' | 'pi';
+export { automaticParticipant } from './participant-identity.js';
 export declare function publicSquarePath(cwd: string): string;
-export declare function automaticParticipant(provider: AutomaticProvider, sessionId: string, env: NodeJS.ProcessEnv): string;
 export declare function automaticSessionStart(provider: AutomaticProvider, sessionId: string, cwd: string, env?: NodeJS.ProcessEnv): Promise<string | undefined>;
 export declare function automaticSessionEnd(provider: AutomaticProvider, sessionId: string, cwd: string, env?: NodeJS.ProcessEnv): Promise<void>;

package/dist/automatic-session.js

@@ -1,4 +1,3 @@
-import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { openSquare } from './square-file-adapter.js';
@@ -7,7 +6,8 @@ import { Square } from './square-wiring.js';
 import { entryPresentation } from './views.js';
 import { canonicalSquarePath, lookupSessionBindings, recordSessionDone, recordSessionJoin } from './registry.js';
 import { participantIdentity, renderAmbientEvent } from './presentation.js';
-import { validateName } from './model.js';
+import { automaticParticipant } from './participant-identity.js';
+export { automaticParticipant } from './participant-identity.js';
 const providerEnv = {
     codex: 'CODEX_THREAD_ID',
     claude: 'CLAUDE_CODE_SESSION_ID',
@@ -17,15 +17,6 @@ const providerEnv = {
 export function publicSquarePath(cwd) {
     return path.join(cwd, '.square', 'PUBLIC.square');
 }
-export function automaticParticipant(provider, sessionId, env) {
-    const configured = env.SQUARE_PARTICIPANT_NAME?.trim();
-    if (configured) {
-        validateName(configured);
-        return configured;
-    }
-    const digest = createHash('sha256').update(sessionId, 'utf8').digest('hex').slice(0, 12);
-    return `${provider}-${digest}`;
-}
 export async function automaticSessionStart(provider, sessionId, cwd, env = process.env) {
     const squarePath = publicSquarePath(cwd);
     if (!fs.existsSync(squarePath))

package/dist/boundary-presentation.d.ts

@@ -2,4 +2,4 @@ import type { InboxMembership } from './model.js';
 /** A fresh blocking catch owns only the notifications admitted by its filter. */
 export declare function pendingAtBoundary(inbox: InboxMembership[]): InboxMembership[];
 export declare function renderPendingAtBoundary(inbox: InboxMembership[]): string;
-export declare function presentPendingAtBoundary<T>(sessionId: string, present: (context: string) => T, lookup?: (sessionId: string) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv): Promise<T | undefined>;
+export declare function presentPendingAtBoundary<T>(sessionId: string, present: (context: string) => T | Promise<T>, lookup?: (sessionId: string) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv): Promise<T | undefined>;

package/dist/boundary-presentation.js

@@ -1,9 +1,7 @@
 import { leaseOwnsNotification } from './delivery.js';
-import { sessionInbox } from './inbox.js';
-import { notificationMessageId } from './delivery.js';
 import { markBoundarySeen } from './square-wiring.js';
-import { renderAttentionPreview } from './attention-presentation.js';
-import { participantCommandPrefix } from './presentation.js';
+import { sessionInbox } from './inbox.js';
+import { ATTENTION_BODY_MAX, renderAttentionPreview } from './attention-presentation.js';
 import { presentOnce } from './presented.js';
 const CONTEXT_MAX = 1200;
 function pendingCount(inbox) {
@@ -24,19 +22,19 @@ export function pendingAtBoundary(inbox) {
         .filter((membership) => membership.notifications.length > 0);
 }
 export function renderPendingAtBoundary(inbox) {
+    return renderBoundary(inbox).context;
+}
+function renderBoundary(inbox) {
     const count = pendingCount(inbox);
     const noun = count === 1 ? 'notification' : 'notifications';
     const header = `<system-reminder source="square">You have ${count} unread Square ${noun}.`;
-    const footer = [
-        'Ids are stable across boundaries. If you already acted on an id, do not repeat the action; still run catch --now to mark delivered.',
-        'Read and respond in the square when appropriate.</system-reminder>',
-    ];
+    const footer = ['Read and respond in the square when appropriate.</system-reminder>'];
     const queued = inbox.flatMap((membership) => membership.notifications.map((notification) => ({ membership, notification })));
     const blocks = [];
+    const complete = [];
     let omitted = 0;
     for (const [index, entry] of queued.entries()) {
         const { membership, notification } = entry;
-        const command = `${participantCommandPrefix(membership.squarePath, membership.name)} catch --now`;
         const block = [
             renderAttentionPreview({
                 squarePath: membership.squarePath,
@@ -46,7 +44,6 @@ export function renderPendingAtBoundary(inbox) {
                 route: notification.route,
                 body: notification.body,
             }),
-            `Ack with: ${command}`,
         ].join('\n');
         const omittedAfter = omitted + queued.length - index - 1;
         const prospective = [
@@ -54,7 +51,7 @@ export function renderPendingAtBoundary(inbox) {
             ...blocks,
             block,
             ...(omittedAfter > 0
-                ? [`… ${omittedAfter} unread ${omittedAfter === 1 ? 'notification' : 'notifications'} omitted. Run catch --now to receive them.`]
+                ? [`… ${omittedAfter} unread ${omittedAfter === 1 ? 'notification' : 'notifications'} omitted.`]
                 : []),
             ...footer,
         ].join('\n');
@@ -63,37 +60,33 @@ export function renderPendingAtBoundary(inbox) {
             continue;
         }
         blocks.push(block);
+        if (notification.body.replace(/\r\n/g, '\n').length <= ATTENTION_BODY_MAX) {
+            complete.push({ membership, actIndexes: [notification.actIndex] });
+        }
     }
-    return [
-        header,
-        ...blocks,
-        ...(omitted > 0
-            ? [`… ${omitted} unread ${omitted === 1 ? 'notification' : 'notifications'} omitted. Run catch --now to receive them.`]
-            : []),
-        ...footer,
-    ].join('\n');
+    return {
+        context: [
+            header,
+            ...blocks,
+            ...(omitted > 0
+                ? [`… ${omitted} unread ${omitted === 1 ? 'notification' : 'notifications'} omitted.`]
+                : []),
+            ...footer,
+        ].join('\n'),
+        complete,
+    };
 }
 export async function presentPendingAtBoundary(sessionId, present, lookup = sessionInbox, env = process.env) {
     const inbox = await lookup(sessionId);
-    let deliveredInbox;
-    let deliveredContext;
-    const result = presentOnce(sessionId, () => pendingAtBoundary(inbox), (inbox) => {
-        const context = renderPendingAtBoundary(inbox);
-        deliveredInbox = inbox;
-        deliveredContext = context;
-        return present(context);
+    let delivered;
+    const result = await presentOnce(sessionId, () => pendingAtBoundary(inbox), (inbox) => {
+        delivered = renderBoundary(inbox);
+        return present(delivered.context);
     }, env);
-    if (result !== undefined && deliveredInbox !== undefined && deliveredContext !== undefined) {
-        await markCompleteBoundaryObservations(deliveredInbox, deliveredContext);
+    if (result !== undefined && delivered !== undefined) {
+        for (const entry of delivered.complete) {
+            await markBoundarySeen(entry.membership.squarePath, entry.membership.name, entry.membership.ownerId, entry.actIndexes);
+        }
     }
     return result;
 }
-async function markCompleteBoundaryObservations(inbox, context) {
-    for (const membership of inbox) {
-        const complete = membership.notifications
-            .filter((notification) => context.includes(notificationMessageId(membership.squarePath, notification.actIndex)) && notification.body.length <= 120)
-            .map((notification) => notification.actIndex);
-        if (complete.length > 0)
-            await markBoundarySeen(membership.squarePath, membership.name, membership.ownerId, complete);
-    }
-}

package/dist/cli/square-commands.js

@@ -7,7 +7,7 @@ import { nowMs } from '../runtime.js';
 import { createSquare, openSquare } from '../square-file-adapter.js';
 import { closeOpenSquare } from '../open-square.js';
 import { openParticipant, Square } from '../square-wiring.js';
-import { admitsBareExpress, entryPresentation, eventPresentation } from '../views.js';
+import { entryPresentation, eventPresentation } from '../views.js';
 import { fail, parseHardCap, parsePositiveInteger, readPipedBodyFallback, readStdinSync, requireParticipant, requireSquarePath, requireValue, resolveBody, usage, } from './context.js';
 function parseBuild(argv) {
     const options = { force: false, hardCap: null };
@@ -178,17 +178,6 @@ export const expressCommand = {
         const squarePath = requireSquarePath(context);
         await sweepPendingNotifications(squarePath);
         const body = resolveBody(intent.activity);
-        if (!intent.force && intent.reach !== 'bell') {
-            const reader = await openSquare(squarePath, { clock: nowMs });
-            try {
-                if (!await admitsBareExpress(reader, intent.name, body)) {
-                    fail(`✕ no one is turned toward you\n  · address someone with @name, ring the bell, or use --force\n» ${participantCommandPrefix(squarePath, intent.name)} express --force -`);
-                }
-            }
-            finally {
-                await closeOpenSquare(reader);
-            }
-        }
         const reachArg = intent.reach === 'bell' ? ' --bell' : '';
         await cmdActivity(squarePath, intent.name, body, (value) => value, {
             force: intent.force,

package/dist/codex-hook.js

@@ -2,13 +2,20 @@ import { presentPendingAtBoundary } from './boundary-presentation.js';
 import { sessionInbox } from './inbox.js';
 import { automaticSessionEnd, automaticSessionStart } from './automatic-session.js';
 import { clearCodexBoundary, recordCodexBoundary } from './codex-boundary-state.js';
+const CODEX_HOOK_EVENTS = {
+    PostToolUse: 'PostToolUse',
+    Stop: 'Stop',
+};
 export async function codexHookResponse(input, lookup = sessionInbox, env = process.env) {
     if (typeof input.session_id !== 'string' || input.session_id === '')
         return undefined;
-    if (input.hook_event_name !== 'PostToolUse' && input.hook_event_name !== 'Stop')
+    if (typeof input.hook_event_name !== 'string')
         return undefined;
-    recordCodexBoundary(input.session_id, input.hook_event_name === 'Stop' ? 'Stop' : 'non-stop', env);
-    return presentPendingAtBoundary(input.session_id, (context) => input.hook_event_name === 'Stop'
+    const hookEventName = CODEX_HOOK_EVENTS[input.hook_event_name];
+    if (hookEventName === undefined)
+        return undefined;
+    recordCodexBoundary(input.session_id, hookEventName === 'Stop' ? 'Stop' : 'non-stop', env);
+    return presentPendingAtBoundary(input.session_id, (context) => hookEventName === 'Stop'
         ? { systemMessage: context }
         : { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: context } }, lookup, env);
 }

package/dist/decisions.js

@@ -2,7 +2,7 @@ import { SquareError, sameName, validateName, } from './model.js';
 import { participantIdentity } from './participant-identity.js';
 import { UNREAD_BLOCK_GRACE_MS, actId, actStableIndex, foldedState, freshWatchLease, publicActs, readCursor, resolveRosterName, rosterNames, THROTTLE_WINDOW_MS, } from './runtime.js';
 import { actDelta, directedPeerSays } from './activity-feed.js';
-import { formatActivityId, isListening, listeningTo, validate } from './square-core.js';
+import { formatActivityId, isIgnored, isListening, listeningTo, validate } from './square-core.js';
 import { deriveDeliveryModel, perceiveActivity } from './delivery.js';
 import { compileSearchPattern } from './search.js';
 export function resolveKnownName(squareState, name) {
@@ -163,7 +163,7 @@ export function coreListen(squareState, actor, target, now) {
     const state = foldedState(squareState);
     const act = { kind: 'listen', actor: resolvedActor, target, at: now };
     requireStanding(squareState, act);
-    return isListening(state, resolvedActor, target) ? undefined : act;
+    return isListening(state, resolvedActor, target) && !isIgnored(state, resolvedActor, target) ? undefined : act;
 }
 export function coreIgnore(squareState, actor, target, now) {
     const resolvedActor = resolveStandingName(squareState, actor);
@@ -171,7 +171,7 @@ export function coreIgnore(squareState, actor, target, now) {
     const state = foldedState(squareState);
     const act = { kind: 'ignore', actor: resolvedActor, target, at: now };
     requireStanding(squareState, act);
-    return isListening(state, resolvedActor, target) ? act : undefined;
+    return isIgnored(state, resolvedActor, target) ? undefined : act;
 }
 export function coreListening(squareState, actor) {
     const resolvedActor = resolveStandingName(squareState, actor);

package/dist/help.js

@@ -18,15 +18,15 @@ const COMMANDS = [
     {
         names: ['express'], usage: '--as <name> express [-f|--force] [--no-wait] [--bell] [--reply <activity-id>] <activity | ->', usesSquare: true, group: 'participant',
         summary: 'Speak, gesture, or do both.',
-        details: ['Reach:', '  @name             Address someone in the square. They hear the body; everyone else sees you walk over.', "  --bell            Call every participant's attention to this activity without a mention.", '  listen             A participant turned toward you also hears your activity.', '', 'Options:', '  -f, --force       Express without first catching unread activity or attention etiquette.', '  --no-wait         If held or throttled, save a draft and return.', '  --reply <activity-id>   Mark this activity as a reply to an earlier activity (for example act/12).'],
+        details: ['Reach:', '  @name             Address someone in the square. They hear the body even without listen; everyone else sees you walk over.', '  bare              Lands in history even with no listener; listen opts someone into future bare delivery.', "  --bell            Call every participant's attention to this activity without a mention.", '', 'Options:', '  -f, --force       Express without first catching unread activity or attention etiquette.', '  --no-wait         If held or throttled, save a draft and return.', '  --reply <activity-id>   Mark this activity as a reply to an earlier activity (for example act/12).'],
     },
     { names: ['listen'], usage: '--as <name> listen <participant>', usesSquare: true, group: 'participant', summary: 'Turn an ear toward one participant\'s future bare says.' },
-    { names: ['ignore'], usage: '--as <name> ignore <participant>', usesSquare: true, group: 'participant', summary: 'Turn away from one participant\'s future bare says.' },
+    { names: ['ignore'], usage: '--as <name> ignore <participant>', usesSquare: true, group: 'participant', summary: 'Ignore one participant\'s future mentions and bare says.' },
     { names: ['listening'], usage: '--as <name> listening', usesSquare: true, group: 'participant', summary: 'Show who you are turned toward.', details: ['Listening is future-only: the edge is fixed when a say lands; it never rewrites history.'] },
     {
         names: ['catch'], usage: '--as <name> catch (--now | --idle <duration>) [--from <names>] [--mention [name]] [--replace]', usesSquare: true, group: 'participant',
         summary: 'Catch directed conversation since you last looked.',
-        details: ['Modes:', '  --now             Catch up immediately.', '  --idle <duration> Wait for something relevant, or for quiet to last this long.', '', 'Attention:', '  Mentions, bells, and bare says from participants you are listening to arrive here.', '  Listener attention is future-only and fixed when each say lands.', '', 'Filters:', '  --from <names>    Match only comma-separated participants.', '  --mention [name]  Match direct attention for a name, or your own name when omitted.', '', 'Recovery:', '  --replace         Replace another active catch for this participant.'],
+        details: ['Modes:', '  --now             Catch up immediately.', '  --idle <duration> Wait for something relevant, or for quiet to last this long.', '', 'Attention:', '  Mentions arrive when you are addressed; bells arrive for everyone; bare says require listen.', '  listen and ignore are future-only and fixed when each say lands.', '', 'Filters:', '  --from <names>    Match only comma-separated participants.', '  --mention [name]  Match direct attention for a name, or your own name when omitted.', '', 'Recovery:', '  --replace         Replace another active catch for this participant.'],
     },
     { names: ['done'], usage: '--as <name> done [final | -]', usesSquare: true, group: 'participant', summary: 'Step out, optionally leaving a final note.' },
     {

package/dist/inbox.d.ts

@@ -1,2 +1,11 @@
 import { type InboxMembership } from './model.js';
+export interface PendingWaitOptions {
+    signal?: AbortSignal;
+    /** Ephemeral watcher de-duplication; never persisted or used by delivery derivation. */
+    excludeKeys?: ReadonlySet<string>;
+    /** After a delivery failure, wait for a new state edge before retrying the same pending work. */
+    skipImmediate?: boolean;
+}
 export declare function sessionInbox(sessionId: string): Promise<InboxMembership[]>;
+/** Wait for a bound square to produce a new pending notification without consuming it. */
+export declare function waitForSessionPending(sessionId: string, timeoutMs: number, options?: PendingWaitOptions): Promise<InboxMembership[]>;

package/dist/inbox.js

@@ -2,6 +2,20 @@ import { lookupSessionBindings } from './registry.js';
 import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
 import { inboxProjection } from './views.js';
+import { waitForSquareChanges } from './square-file-adapter.js';
+function notificationKey(membership, actIndex) {
+    return `${membership.squarePath}\u0000${membership.name.toLocaleLowerCase()}\u0000${actIndex}`;
+}
+function withoutExcluded(inbox, excludeKeys) {
+    if (excludeKeys === undefined || excludeKeys.size === 0)
+        return inbox;
+    return inbox
+        .map((membership) => ({
+        ...membership,
+        notifications: membership.notifications.filter((notification) => !excludeKeys.has(notificationKey(membership, notification.actIndex))),
+    }))
+        .filter((membership) => membership.notifications.length > 0);
+}
 export async function sessionInbox(sessionId) {
     const inbox = [];
     for (const binding of lookupSessionBindings(sessionId)) {
@@ -29,3 +43,42 @@ export async function sessionInbox(sessionId) {
     }
     return inbox;
 }
+/** Wait for a bound square to produce a new pending notification without consuming it. */
+export async function waitForSessionPending(sessionId, timeoutMs, options = {}) {
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    if (!options.skipImmediate) {
+        const immediate = withoutExcluded(await sessionInbox(sessionId), options.excludeKeys);
+        if (immediate.some((membership) => membership.notifications.length > 0))
+            return immediate;
+    }
+    if (timeoutMs <= 0 || options.signal?.aborted)
+        return [];
+    const bindings = lookupSessionBindings(sessionId);
+    const paths = [...new Set(bindings.map((binding) => binding.squarePath))];
+    let aborted = false;
+    let projectAfterReady = !options.skipImmediate;
+    const onAbort = () => { aborted = true; };
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        while (!aborted) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return [];
+            const change = await waitForSquareChanges(paths, remaining, options.signal, async () => {
+                if (!projectAfterReady)
+                    return undefined;
+                const current = withoutExcluded(await sessionInbox(sessionId), options.excludeKeys);
+                return current.some((membership) => membership.notifications.length > 0) ? current : undefined;
+            });
+            if (aborted || change.status === 'expired')
+                return [];
+            if (change.status === 'ready')
+                return change.value;
+            projectAfterReady = true;
+        }
+        return [];
+    }
+    finally {
+        options.signal?.removeEventListener('abort', onAbort);
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Square } from './square-wiring.js';
 export { SquareError } from './model.js';
-export { assignedSquareName, bindCurrentParticipant, unbindCurrentParticipant } from './registry.js';
+export { bindCurrentParticipant, squareAssignedParticipantName, unbindCurrentParticipant } from './registry.js';
 export type { ActivityId } from './square-core.js';
 export type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, HistoryQuery, ListenerChangeResult, OpenOptions, Participant, ParticipantStatus, PerceivedActivity, SquareAtInput, SquareBuildInput, SquareSnapshot, SquareSource, WakeNotifier, } from './square-facade.js';

package/dist/index.js

@@ -1,3 +1,3 @@
 export { Square } from './square-wiring.js';
 export { SquareError } from './model.js';
-export { assignedSquareName, bindCurrentParticipant, unbindCurrentParticipant } from './registry.js';
+export { bindCurrentParticipant, squareAssignedParticipantName, unbindCurrentParticipant } from './registry.js';