@astrosheep/square 0.3.11 → 0.3.12

package/dist/boundary-presentation.js

@@ -16,7 +16,7 @@ export function pendingAtBoundary(inbox) {
             return membership;
         return {
             ...membership,
-            notifications: membership.notifications.filter((notification) => !leaseOwnsNotification(lease, { ...notification, recipient: membership.name })),
+            notifications: membership.notifications.filter((notification) => !leaseOwnsNotification(lease, notification)),
         };
     })
         .filter((membership) => membership.notifications.length > 0);

package/dist/cli/context.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { loadSquare } from '../artifact.js';
 import { commandUsageHint } from '../help.js';
 import { parseParticipantList, validateName } from '../model.js';
-export const DEFAULT_SQUARE_PATH = '.square/SQUARE.md';
+export const DEFAULT_SQUARE_PATH = '.square/SQUARE.square';
 export function readStdinSync() {
     try {
         return fs.readFileSync(0, 'utf8');
@@ -99,7 +99,7 @@ function resolveDefaultSquarePath() {
     }
     const candidates = [];
     for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith('.md'))
+        if (!entry.isFile() || !entry.name.endsWith('.square'))
             continue;
         const fullPath = path.join(directory, entry.name);
         try {

package/dist/cli/harness-command.js

@@ -87,7 +87,7 @@ export function formatHarnessResult(result) {
     return `${[...result.notes, ...result.lines].join('\n')}\n`;
 }
 export function runHarnessCommand(argv, squarePath) {
-    const context = { homeDir: os.homedir(), squarePath: squarePath ?? '.square/SQUARE.md', command: 'harness' };
+    const context = { homeDir: os.homedir(), squarePath: squarePath ?? '.square/SQUARE.square', command: 'harness' };
     const intent = harnessCommand.parse(argv, context);
     return Promise.resolve(harnessCommand.execute(intent, context)).then(formatHarnessResult);
 }

package/dist/cli/maintenance-commands.js

@@ -1,82 +1,25 @@
-import fs from 'node:fs';
-import { diagnoseSquare, loadSquare } from '../artifact.js';
-import { renderDoctorClean, renderDoctorProblems, renderDoctorRepaired, renderDoctorUnfixable, withPathOutput, } from '../presentation.js';
+import { diagnoseSquareFile } from '../artifact.js';
+import { renderDoctorClean, renderDoctorUnfixable, withPathOutput } from '../presentation.js';
 import { inSquareCount } from '../runtime.js';
-import { repairSquare } from '../square-application.js';
-import { SquareError } from '../model.js';
-import { pruneRegistry } from '../registry.js';
 import { usage } from './context.js';
-function readSquareText(squarePath) {
-    try {
-        return fs.readFileSync(squarePath, 'utf8');
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            throw new SquareError('not_found', `square file not found: ${squarePath}`);
-        throw error;
-    }
-}
-function quarantinePath(squarePath) {
-    return squarePath.replace(/\.md$/, '') + '.quarantine.md';
-}
-function registryActs(squarePath) {
-    if (!fs.existsSync(squarePath))
-        return [];
-    try {
-        return loadSquare(squarePath).acts;
-    }
-    catch {
-        // A temporarily unreadable artifact cannot disprove a cache binding.
-        return undefined;
-    }
-}
 export const doctorCommand = {
     parse(argv, context) {
-        let fix = false;
-        for (let index = 0; index < argv.length; index++) {
-            const argument = argv[index];
-            if (argument === '--fix')
-                fix = true;
-            else if (argument === '--before') {
-                index += 1;
-                if (argv[index] === undefined)
-                    usage(context.command);
-            }
-            else
-                usage(context.command);
-        }
-        return { fix };
+        if (argv.length > 0)
+            usage(context.command);
+        return undefined;
     },
-    async execute(intent, context) {
-        if (!intent.fix) {
-            const diagnosis = diagnoseSquare(readSquareText(context.squarePath));
-            if (diagnosis.unfixable) {
-                return {
-                    output: withPathOutput(context.squarePath, renderDoctorUnfixable(diagnosis.unfixable), { participantCount: inSquareCount(loadSquare(context.squarePath)) }),
-                    exitCode: 2,
-                };
-            }
-            const summary = diagnosis.problems.length === 0 ? renderDoctorClean() : renderDoctorProblems(diagnosis.problems);
+    execute(_intent, context) {
+        const diagnosis = diagnoseSquareFile(context.squarePath);
+        if (diagnosis.unfixable !== undefined || diagnosis.doc === undefined) {
             return {
-                output: withPathOutput(context.squarePath, summary, { participantCount: inSquareCount(loadSquare(context.squarePath)) }),
-                exitCode: diagnosis.problems.length === 0 ? 0 : 1,
-            };
-        }
-        const repair = await repairSquare(context.squarePath);
-        if (repair.diagnosis.unfixable) {
-            return {
-                output: withPathOutput(context.squarePath, renderDoctorUnfixable(repair.diagnosis.unfixable), { participantCount: inSquareCount(loadSquare(context.squarePath)) }),
+                output: withPathOutput(context.squarePath, renderDoctorUnfixable(diagnosis.unfixable ?? 'the snapshot could not be decoded')),
                 exitCode: 2,
             };
         }
-        const repaired = repair.repaired;
-        const registry = pruneRegistry(registryActs);
-        if (registry.removed > 0) {
-            repaired.actions.push({ message: `pruned ${registry.removed} obsolete registry membership(s)` });
-        }
-        const sidecar = quarantinePath(context.squarePath);
         return {
-            output: withPathOutput(context.squarePath, renderDoctorRepaired(repaired.actions, repaired.quarantinedBlocks.length, repaired.quarantinedBlocks.length > 0 ? sidecar : undefined), { participantCount: inSquareCount(loadSquare(context.squarePath)) }),
+            output: withPathOutput(context.squarePath, renderDoctorClean(), {
+                participantCount: inSquareCount(diagnosis.doc),
+            }),
         };
     },
     present(result) {

package/dist/cli/observation-commands.js

@@ -6,7 +6,8 @@ import { sessionInbox } from '../inbox.js';
 import { sweepPendingNotifications } from '../notifications.js';
 import { cmdListSquares } from '../list.js';
 import { sameName } from '../model.js';
-import { commandPrefix, participantCommandPrefix, renderActivitiesView, renderGrepActivitiesView, renderVisibleEvent, withPathOutput, } from '../presentation.js';
+import { parseActivityId } from '../square-core.js';
+import { commandPrefix, participantCommandPrefix, renderActivitiesView, renderGrepActivitiesView, renderAmbientEvent, withPathOutput, } from '../presentation.js';
 import { actId, inSquareCount, nowMs, sayNumberFor } from '../runtime.js';
 import { cmdStream, cmdStreamNdjson } from '../stream.js';
 import { formatRelativeTime, formatTimestamp, parseTimeOrRelative } from '../time.js';
@@ -98,10 +99,10 @@ export const catchCommand = {
     present: () => { },
 };
 function parseActRef(value, flag) {
-    const match = value.trim().match(/^(?:act_)?(\d+)$/i);
-    if (!match)
-        fail(`Invalid ${flag}: expected an activity id like act_12 or 12.`);
-    return Number(match[1]);
+    const index = parseActivityId(value);
+    if (index === undefined)
+        fail(`Invalid ${flag}: expected an activity id like act/12`);
+    return index;
 }
 function parseTimestamp(value, flag) {
     const timestamp = parseTimeOrRelative(value, nowMs());
@@ -305,24 +306,16 @@ export const historyCommand = {
             return events.map((item) => renderFields(doc, item, options.format)).join('\n') + (events.length > 0 ? '\n' : '');
         }
         const pattern = options.grep ?? options.fixed;
+        const archive = options.atIndex != null
+            || (options.ids !== undefined && options.ids.length > 0)
+            || (options.lastN == null && options.full === true);
         const output = pattern === undefined || pattern === ''
-            ? renderActivitiesView(doc, events, null, options.full, context.squarePath, options.viewer ?? '')
+            ? renderActivitiesView(doc, events, null, options.full, context.squarePath, options.viewer ?? '', archive ? 'archive' : 'ambient')
             : renderGrepActivitiesView(events, totalMatches, options.full, context.squarePath, pattern, options.fixed !== undefined);
         return withPathOutput(context.squarePath, output, { participantCount: inSquareCount(doc) });
     },
     present: (result) => process.stdout.write(result),
 };
-export const warmupCommand = {
-    parse(argv, context) { if (argv.length > 0)
-        usage(context.command); return undefined; },
-    execute(_intent, context) {
-        const doc = loadSquare(context.squarePath);
-        return withPathOutput(context.squarePath, doc.warmup.join('\n'), {
-            participantCount: inSquareCount(doc),
-        });
-    },
-    present: (result) => process.stdout.write(result),
-};
 export const participantsCommand = {
     parse(argv, context) { if (argv.length > 0)
         usage(context.command); return undefined; },
@@ -383,7 +376,7 @@ export const statusCommand = {
             : undefined;
         const visible = result.latestAct === undefined
             ? ''
-            : renderVisibleEvent(doc.acts, result.latestAct, context.name ?? '', {
+            : renderAmbientEvent(result.latestAct, context.name ?? '', {
                 now: result.now,
                 preview: 200,
                 actNumber: result.latestAct.kind === 'say'

package/dist/cli/program.js

@@ -3,9 +3,10 @@ import { SquareError } from '../model.js';
 import { defaultContext, parseGlobalArgs } from './context.js';
 import { executeRegisteredCommand, findCommand } from './registry.js';
 function isMutatingCommand(command, argv) {
+    void argv;
     if (['build', 'join', 'catch', 'express', 'done', 'hold', 'resume', 'compact'].includes(command))
         return true;
-    return command === 'doctor' && argv.includes('--fix');
+    return false;
 }
 function handleSquareError(error) {
     if (error instanceof SquareError) {
@@ -19,7 +20,7 @@ export async function runCli(rawArgs = process.argv.slice(2)) {
     try {
         const requestedHelp = helpRequest(rawArgs);
         if (requestedHelp !== undefined) {
-            await executeRegisteredCommand('help', requestedHelp.command === undefined ? [] : [requestedHelp.command], defaultContext('help', '.square/SQUARE.md'));
+            await executeRegisteredCommand('help', requestedHelp.command === undefined ? [] : [requestedHelp.command], defaultContext('help', '.square/SQUARE.square'));
             return;
         }
         const parsed = parseGlobalArgs(rawArgs);

package/dist/cli/registry.js

@@ -2,7 +2,7 @@ import { buildCommand, compactCommand, doneCommand, expressCommand, holdCommand,
 import { doctorCommand } from './maintenance-commands.js';
 import { harnessCommand, installCommand, uninstallCommand } from './harness-command.js';
 import { helpCommand, versionCommand } from './meta-commands.js';
-import { catchCommand, claudeHookCommand, codexHookCommand, historyCommand, inboxCommand, listCommand, participantsCommand, statusCommand, streamCommand, warmupCommand, } from './observation-commands.js';
+import { catchCommand, claudeHookCommand, codexHookCommand, historyCommand, inboxCommand, listCommand, participantsCommand, statusCommand, streamCommand, } from './observation-commands.js';
 /** Every public command is an executable adapter, including aliases and utility commands. */
 export const commandRegistry = [
     { names: ['build'], spec: buildCommand },
@@ -23,7 +23,6 @@ export const commandRegistry = [
     { names: ['compact'], spec: compactCommand },
     { names: ['doctor'], spec: doctorCommand },
     { names: ['history'], spec: historyCommand },
-    { names: ['warmup'], spec: warmupCommand },
     { names: ['status'], spec: statusCommand },
     { names: ['participants'], spec: participantsCommand },
     { names: ['help'], spec: helpCommand },

package/dist/cli/square-commands.js

@@ -2,11 +2,12 @@ import { cmdActivity } from '../activity.js';
 import { loadSquare } from '../artifact.js';
 import { cmdCompact } from '../compact.js';
 import { SquareError, formatHardCap, validateName, } from '../model.js';
-import { participantCommandPrefix, quoteShell, renderEventCli, renderPublicTail, withPathOutput, } from '../presentation.js';
+import { participantCommandPrefix, renderEventCli, renderPublicTail, withPathOutput, } from '../presentation.js';
 import { hasAutomaticDeliveryIdentity, localParticipantOwner, recordLocalDone, recordLocalJoin } from '../registry.js';
 import { sweepPendingNotifications } from '../notifications.js';
 import { inSquareCount, isCurrentlyJoined, nowMs, resolveRosterName } from '../runtime.js';
 import { createSquare, execute } from '../square-application.js';
+import { formatActivityId, parseActivityId } from '../square-core.js';
 import { fail, parseHardCap, parsePositiveInteger, readPipedBodyFallback, readStdinSync, requireParticipant, requireValue, resolveBody, usage, } from './context.js';
 function parseBuild(argv) {
     const options = { force: false, hardCap: null };
@@ -92,11 +93,12 @@ export const joinCommand = {
             const fallback = hasAutomaticDeliveryIdentity()
                 ? []
                 : ['', `» ${participantCommandPrefix(context.squarePath, joinedName)} catch --idle 30m`, '  no session delivery detected — keep this catch open for new activity'];
+            const scene = after.warmup.join('\n').trim();
             const output = [
-                `● ${joinedName} stepped into the square`,
+                `● You stepped into the square`,
+                ...(isRejoin || scene === '' ? [] : ['', scene]),
                 ...(isRejoin || contextText === '' ? [] : ['', 'context', contextText]),
                 ...(activities === '' ? [] : ['', 'recent activity', activities]),
-                ...(isRejoin ? [] : ['', `» ${participantCommandPrefix(context.squarePath, joinedName)} warmup`]),
                 ...fallback,
             ].join('\n');
             return withPathOutput(context.squarePath, output, { participantCount: inSquareCount(after) });
@@ -125,7 +127,9 @@ export const joinCommand = {
             const line = reconnect && !intent.kick
                 ? `● you are already in the square`
                 : `✓ you banished the original ${joinedName} — the name is yours`;
-            return withPathOutput(context.squarePath, `${line}${fallback}`, { participantCount: inSquareCount(doc) });
+            const scene = doc.warmup.join('\n').trim();
+            const showScene = !(reconnect && !intent.kick) && scene !== '';
+            return withPathOutput(context.squarePath, `${line}${showScene ? `\n\n${scene}` : ''}${fallback}`, { participantCount: inSquareCount(doc) });
         }
     },
     present: (result) => process.stdout.write(result),
@@ -133,7 +137,6 @@ export const joinCommand = {
 function parseActivity(argv, context) {
     let force = false;
     let noWait = false;
-    let beside;
     let bell = false;
     let reply;
     const bodyArgs = [];
@@ -143,25 +146,21 @@ function parseActivity(argv, context) {
             force = true;
         else if (argument === '--no-wait')
             noWait = true;
-        else if (argument === '--beside') {
-            beside = requireValue(argv, index, argument);
-            index += 1;
-        }
+        else if (argument === '--beside')
+            fail('✕ express does not know --beside\n» square express --help');
         else if (argument === '--bell')
             bell = true;
         else if (argument === '--reply') {
-            const value = requireValue(argv, index, argument).trim().match(/^(?:act_)?(\d+)$/i);
-            if (!value || !Number.isSafeInteger(Number(value[1])))
-                fail('Invalid --reply: expected an activity id like act_12 or 12.');
-            reply = Number(value[1]);
+            const replyIndex = parseActivityId(requireValue(argv, index, argument));
+            if (replyIndex === undefined)
+                fail('Invalid --reply: expected an activity id like act/12');
+            reply = replyIndex;
             index += 1;
         }
         else
             bodyArgs.push(argument);
     }
-    if (bell && beside !== undefined)
-        fail('Invalid express options: --beside and --bell are mutually exclusive.');
-    const reach = bell ? 'bell' : beside === undefined ? undefined : { beside };
+    const reach = bell ? 'bell' : undefined;
     if (bodyArgs.length !== 1) {
         if (bodyArgs.length === 0) {
             const piped = readPipedBodyFallback();
@@ -176,13 +175,13 @@ export const expressCommand = {
     parse: parseActivity,
     async execute(intent, context) {
         await sweepPendingNotifications(context.squarePath);
-        const reachArg = intent.reach === 'bell' ? ' --bell' : intent.reach === undefined ? '' : ` --beside ${quoteShell(intent.reach.beside)}`;
+        const reachArg = intent.reach === 'bell' ? ' --bell' : '';
         await cmdActivity(context.squarePath, intent.name, intent.activity, resolveBody, {
             force: intent.force,
             noWait: intent.noWait,
             reach: intent.reach,
             reply: intent.reply,
-            forceCommand: `${participantCommandPrefix(context.squarePath, intent.name)} express --force${reachArg}${intent.reply === undefined ? '' : ` --reply act_${intent.reply}`} -`,
+            forceCommand: `${participantCommandPrefix(context.squarePath, intent.name)} express --force${reachArg}${intent.reply === undefined ? '' : ` --reply ${formatActivityId(intent.reply)}`} -`,
         });
     },
     present: () => { },

package/dist/compact.js

@@ -1,19 +1,19 @@
 import { SquareError } from './model.js';
 import { withPathOutput } from './presentation.js';
 import { execute } from './square-application.js';
-function sidecarPath(squarePath) {
-    return squarePath.replace(/\.md$/, '') + '.archive.md';
+function archivePath(squarePath) {
+    return squarePath.replace(/\.square$/, '') + '.archive.square';
 }
 export async function cmdCompact(squarePath, opts) {
     try {
         let archivedCount;
         let keptCount;
-        const archive = sidecarPath(squarePath);
+        const archive = archivePath(squarePath);
         const committed = await execute(squarePath, { type: 'compact', keep: opts.keep, archivePath: archive });
         const result = committed.result;
         archivedCount = result.archived.length;
         keptCount = result.doc.acts.length;
-        const summary = ['✓ compacted', `  · archived ${archivedCount} activities`, `  · kept ${keptCount} activities`, ...(archivedCount > 0 ? [`  · sidecar ${archive}`] : [])].join('\n');
+        const summary = ['✓ compacted', `  · archived ${archivedCount} activities`, `  · kept ${keptCount} activities`, ...(archivedCount > 0 ? [`  · archive ${archive}`] : [])].join('\n');
         process.stdout.write(withPathOutput(squarePath, summary));
     }
     catch (err) {

package/dist/decisions.js

@@ -1,7 +1,7 @@
 import { SquareError, sameName, validateName, } from './model.js';
 import { UNREAD_BLOCK_GRACE_MS, actId, actStableIndex, foldedState, freshWatchLease, getReadState, publicActs, readCursor, resolveRosterName, rosterNames, matchesMentionTarget, THROTTLE_WINDOW_MS, } from './runtime.js';
 import { actDelta, peerPublicActs, peerRoomChanges } from './activity-feed.js';
-import { validate } from './square-core.js';
+import { extractMentions, formatActivityId, validate } from './square-core.js';
 import { deriveDeliveryModel } from './delivery.js';
 import { compileSearchPattern } from './search.js';
 export function resolveKnownName(doc, name) {
@@ -27,7 +27,7 @@ export function decideJoin(doc, name, now) {
     return {
         joinedName,
         addParticipant: knownName === undefined,
-        joinAct: { kind: 'join', actor: joinedName, at: now, body: '' },
+        joinAct: { kind: 'join', actor: joinedName, at: now },
     };
 }
 const UNREAD_PREVIEW_LIMIT = 3;
@@ -41,10 +41,15 @@ export function decideAct(doc, input) {
     const reply = input.reply;
     if (reply !== undefined) {
         if (!Number.isSafeInteger(reply) || reply < 0 || reply >= doc.runtime.nextActIndex) {
-            throw new SquareError('invalid_args', `Unknown reply activity: act_${reply}`);
+            const label = Number.isSafeInteger(reply) && reply >= 0 ? formatActivityId(reply) : String(reply);
+            throw new SquareError('invalid_args', `Unknown reply activity: ${label}`);
         }
     }
     const state = foldedState(doc);
+    if (reach !== 'bell'
+        && extractMentions(body).length === 0) {
+        throw new SquareError('invalid_args', 'express requires an @mention unless using --bell');
+    }
     const current = participantState(state, name);
     const result = validate(state, {
         kind: 'say', actor: name, at: now, body,
@@ -97,7 +102,8 @@ export function decideAct(doc, input) {
     }))
         .sort((a, b) => a.latestActivityAgeMs - b.latestActivityAgeMs || a.name.localeCompare(b.name));
     const latestActivityAgeMs = activitySummaries[0]?.latestActivityAgeMs;
-    const hasUnread = unreadPublic.length > 0 || unreadRoomChanges.length > 0;
+    const hasUnreadBlockingChange = unreadRoomChanges.some((act) => act.kind !== 'join');
+    const hasUnread = unreadPublic.length > 0 || hasUnreadBlockingChange;
     const hasFreshUnreadActivity = latestActivityAgeMs !== undefined && latestActivityAgeMs <= UNREAD_BLOCK_GRACE_MS;
     if (!force && hasUnread && !hasFreshUnreadActivity) {
         return { type: 'blocked', activitySummaries, unreadRoomChanges };
@@ -124,7 +130,7 @@ export function coreHold(_doc, actor, body, now) {
     return { kind: 'hold', actor, at: now, body: body.replace(/\r\n/g, '\n').trim() };
 }
 export function coreResume(_doc, actor, now) {
-    return { kind: 'resume', actor, at: now, body: '' };
+    return { kind: 'resume', actor, at: now };
 }
 function presenceFor(doc, snapshot, name, now) {
     if (snapshot?.done)

package/dist/delivery-health.js

@@ -1,5 +1,6 @@
 import { loadSquare } from './artifact.js';
 import { deriveDeliveryModel, } from './delivery.js';
+import { formatActivityId } from './square-core.js';
 import { formatDuration } from './time.js';
 import { joinedRecipients, wakeEvidence } from './wake-evidence.js';
 const DISPLAY_ORDER = [
@@ -44,7 +45,7 @@ export function classifyDeliveryHealth(squarePath, opts) {
 }
 function formatItem(item) {
     const evidence = item.attempt?.signature === undefined ? '' : ` · ${item.attempt.signature}`;
-    return `  · act_${item.actIndex} → @${item.recipient} from @${item.actor} · ${formatDuration(item.ageMs)}${evidence}`;
+    return `  · ${formatActivityId(item.actIndex)} → @${item.recipient} from @${item.actor} · ${formatDuration(item.ageMs)}${evidence}`;
 }
 export function doctorDeliveryHealth(squarePath, graceMs, now = Date.now(), env = process.env) {
     const items = classifyDeliveryHealth(squarePath, { graceMs, now, env });

package/dist/delivery.js

@@ -1,10 +1,8 @@
 import { findParticipantName, sameName, } from './model.js';
-import { actId, extractMentions, isCurrentlyJoined, lastJoinIndex, matchesMentionTarget, resolveRosterName, rosterNames } from './runtime.js';
+import { audienceOf, formatActivityId, resolveAudience } from './square-core.js';
+import { actId, isCurrentlyJoined, lastJoinIndex, matchesMentionTarget, resolveRosterName, rosterNames } from './runtime.js';
 export function notificationMessageId(squarePath, actIndex) {
-    return `square:${squarePath}#act_${actIndex}`;
-}
-export function isPendingNotification(notification) {
-    return notification.route !== 'broadcast';
+    return `square:${squarePath}#${formatActivityId(actIndex)}`;
 }
 function canonicalRecipient(doc, name) {
     return resolveRosterName(doc, name) ?? name;
@@ -32,16 +30,6 @@ export function recordDeliveredRuntime(runtime, recipient, actOrIndex, receipt)
 export function markDeliveredDelivery(doc, name, actOrIndex, at = Date.now()) {
     return recordDeliveredDelivery(doc, name, actOrIndex, { at });
 }
-function uniqueKnownMentions(body, roster) {
-    const recipients = [];
-    for (const mention of extractMentions(body)) {
-        const known = findParticipantName(roster, mention);
-        if (known !== undefined && !recipients.some((recipient) => sameName(recipient, known))) {
-            recipients.push(known);
-        }
-    }
-    return recipients;
-}
 /**
  * Derive delivery behavior once from the parsed Square document.
  * All consumers share these targets instead of reinterpreting artifact text or cursor state.
@@ -53,23 +41,9 @@ export function deriveDeliveryModel(doc) {
         if (item.kind !== 'say')
             return [];
         const sayItem = item;
-        const actor = sayItem.actor;
-        if (sayItem.reach === 'bell') {
-            return roster
-                .filter((recipient) => !sameName(recipient, actor))
-                .map((recipient) => ({ item: sayItem, recipient, route: 'bell' }));
-        }
-        if (sayItem.reach !== undefined) {
-            const recipient = findParticipantName(roster, sayItem.reach.beside);
-            return recipient === undefined || sameName(recipient, actor)
-                ? []
-                : [{ item: sayItem, recipient, route: 'beside' }];
-        }
-        const mentions = uniqueKnownMentions(sayItem.body, roster).filter((recipient) => !sameName(recipient, actor));
-        const recipients = mentions.length > 0
-            ? mentions
-            : roster.filter((recipient) => !sameName(recipient, actor));
-        const route = mentions.length > 0 ? 'mention' : 'broadcast';
+        const audience = audienceOf(sayItem);
+        const recipients = resolveAudience(audience, roster).filter((recipient) => !sameName(recipient, sayItem.actor));
+        const route = audience.kind === 'bell' ? 'bell' : 'mention';
         return recipients.map((recipient) => ({ item: sayItem, recipient, route }));
     }
     function pendingFor(requestedRecipient) {
@@ -82,19 +56,16 @@ export function deriveDeliveryModel(doc) {
             for (const act of doc.acts) {
                 if (act.kind !== 'say')
                     continue;
-                // Broadcasts can never be pending directed notifications. Skipping them here
-                // avoids allocating one planned notification per participant per activity.
-                if (act.reach === undefined && extractMentions(act.body).length === 0)
+                const audience = audienceOf(act);
+                if (audience.kind === 'mentions' && audience.names.length === 0)
                     continue;
                 for (const planned of plan(act)) {
-                    if (planned.route === 'broadcast')
-                        continue;
                     const joinedAt = joinedAfter.get(planned.recipient);
                     if (joinedAt === undefined || act.index <= joinedAt)
                         continue;
                     if (isDeliveryDelivered(doc, planned.recipient, act.index))
                         continue;
-                    pendingByRecipient.get(planned.recipient)?.push({ ...planned, route: planned.route });
+                    pendingByRecipient.get(planned.recipient)?.push(planned);
                 }
             }
         }
@@ -118,7 +89,7 @@ export function markDeliveredNotifications(doc, recipient, delivered, at = Date.
 }
 /** Canonical say-activity filter shared by catch selection and hook ownership. */
 export function matchesCatchFilter(activity, filter) {
-    if (activity.reach === 'bell')
+    if (audienceOf(activity).kind === 'bell')
         return true;
     if (filter.participants !== undefined &&
         !filter.participants.some((participant) => sameName(participant, activity.actor))) {
@@ -128,16 +99,9 @@ export function matchesCatchFilter(activity, filter) {
 }
 /** True only when the live catch's own filters would deliver this notification. */
 export function leaseOwnsNotification(lease, notification) {
-    const recipient = notification.recipient;
-    if (notification.route === 'beside' && recipient === undefined)
-        return false;
     return matchesCatchFilter({
         actor: notification.actor,
         body: notification.body,
-        reach: notification.route === 'bell'
-            ? 'bell'
-            : notification.route === 'beside'
-                ? { beside: recipient }
-                : undefined,
+        ...(notification.route === 'bell' ? { reach: 'bell' } : {}),
     }, lease.filter ?? {});
 }

package/dist/help.js

@@ -16,9 +16,9 @@ const COMMANDS = [
         details: ['Options:', '  --last <N>  Show the last N public activities (default 10).', '  --all       Show the complete history.'],
     },
     {
-        names: ['express'], usage: '--as <name> express [-f|--force] [--no-wait] [--beside <name> | --bell] [--reply <act_N>] <activity | ->', usesSquare: true, group: 'participant',
+        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: ['Options:', '  -f, --force       Express without first catching unread activity.', '  --no-wait         If held or throttled, save a draft and return.', '  --beside <name>   Speak aside to one participant.', "  --bell            Call every participant's attention to this activity.", '  --reply <act_N>   Mark this activity as a reply to an earlier activity.'],
+        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.", '', 'Options:', '  -f, --force       Express without first catching unread activity.', '  --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: ['catch'], usage: '--as <name> catch (--now | --idle <duration>) [--from <names>] [--mention [name]] [--replace]', usesSquare: true, group: 'participant',
@@ -39,10 +39,9 @@ const COMMANDS = [
     { names: ['claude-hook', 'codex-hook'], usage: '{command}', summary: 'Present pending attention at one native agent boundary.', hiddenFromIndex: true },
     {
         names: ['history'], usage: '[--as <name>] history [filters] [output]', usesSquare: true, group: 'participant',
-        summary: 'Read or search what happened without changing what you have caught.',
-        details: ['Filters:', '  --from <names>                  Match activities from participants.', '  --since <time>, --until <time>  Match a time window.', '  --grep <regex> | --fixed <s>    Search ids, participant names, and bodies.', '  --mention <name>                Match mentions.', '  --pending                       Match attention waiting for --as <name>.', '  --ids <ids> | --at <id>         Match stable activity ids.', '  -B, -A, -C <N>                 Set non-negative context around --at.', '  --after <id>                    Match activities after an id.', '', 'Results:', '  --limit <N> | --all             Bound the newest matches (default 10).', '  --order <asc|desc>              Set display order.', '', 'Output:', '  --full  --json  --format <fields>  --count'],
+        summary: 'Read or search the archive without changing what you have caught.',
+        details: ['Filters:', '  --from <names>                  Match activities from participants.', '  --since <time>, --until <time>  Match a time window.', '  --grep <regex> | --fixed <s>    Search ids, participant names, and original bodies.', '  --mention <name>                Match mentions.', '  --pending                       Match attention waiting for --as <name>.', '  --ids <ids> | --at <id>         Match stable activity ids and show original bodies.', '  -B, -A, -C <N>                 Set non-negative context around --at.', '  --after <id>                    Match activities after an id.', '', 'Results:', '  --limit <N> | --all             Bound the newest matches (default 10).', '  --order <asc|desc>              Set display order.', '', 'Output:', '  --full  --json  --format <fields>  --count'],
     },
-    { names: ['warmup'], usage: 'warmup', usesSquare: true, group: 'host', summary: 'Print the complete embedded participant warmup.' },
     { names: ['status'], usage: '[--as <name>] status', usesSquare: true, group: 'participant', summary: 'Show who is present and what happened most recently.' },
     { names: ['participants'], usage: 'participants', usesSquare: true, group: 'host', summary: 'Show the full participant roster and current states.' },
     { names: ['hold'], usage: '--as <name> hold [reason | -]', usesSquare: true, group: 'participant', summary: 'Raise a hand and pause participant activity.' },
@@ -64,9 +63,8 @@ const COMMANDS = [
     },
     { names: ['compact'], usage: 'compact [--keep N]', usesSquare: true, group: 'host', summary: 'Move older activity out of the working artifact while keeping the latest N.' },
     {
-        names: ['doctor'], usage: 'doctor [--fix]', usesSquare: true, group: 'maintenance',
-        summary: 'Diagnose artifact integrity.',
-        details: ['Options:', '  --fix              Repair recoverable artifact problems.'],
+        names: ['doctor'], usage: 'doctor', usesSquare: true, group: 'maintenance',
+        summary: 'Validate binary artifact integrity.',
     },
 ];
 function definitionFor(command) {
@@ -78,8 +76,8 @@ function isHelpFlag(value) {
 export function renderGlobalHelp() {
     const groups = [
         { key: 'participant', title: 'In the square:', order: ['join', 'express', 'catch', 'history', 'status', 'hold', 'resume', 'done'] },
-        { key: 'host', title: 'Prepare and manage:', order: ['build', 'list', 'participants', 'warmup', 'compact'] },
-        { key: 'maintenance', title: 'Setup and repair:', order: ['install', 'uninstall', 'doctor'] },
+        { key: 'host', title: 'Prepare and manage:', order: ['build', 'list', 'participants', 'compact'] },
+        { key: 'maintenance', title: 'Setup:', order: ['install', 'uninstall', 'doctor'] },
     ];
     const commandLines = groups.flatMap(({ key, title, order }) => [
         title,

package/dist/index.js

@@ -1,19 +1,21 @@
 export { SquareError } from './model.js';
+export { extractMentions, formatActivityId, parseActivityId } from './square-core.js';
 export { loadSquare } from './artifact.js';
-export { extractMentions, countSays, joinedNames, doneNames, isCurrentlyJoined, publicActs, readCursor, } from './runtime.js';
+export { countSays, joinedNames, doneNames, isCurrentlyJoined, publicActs, readCursor, } from './runtime.js';
 import { loadSquare } from './artifact.js';
 import { dispatchActNotifications, hasDeliveredNotification as hasDeliveredNotificationImpl, sweepPendingNotifications, waitForDeliveredNotification as waitForDeliveredNotificationImpl, } from './notifications.js';
 import { WATCH_STALE_MS, freshWatchLease, getReadState as getDocReadState, } from './runtime.js';
 import { resolveKnownName } from './decisions.js';
 import { execute } from './square-application.js';
+import { parseActivityId } from './square-core.js';
 export { WATCH_STALE_MS };
 function actRefIndex(ref) {
     if (typeof ref === 'number')
         return ref;
-    const match = ref.match(/^act_(\d+)$/);
-    if (!match)
+    const index = parseActivityId(ref);
+    if (index === undefined)
         throw new Error(`Invalid act ref: ${ref}`);
-    return Number(match[1]);
+    return index;
 }
 export function getReadState(squarePath, name) {
     const doc = loadSquare(squarePath);