@astrosheep/square 0.3.58 → 0.3.62

package/dist/cli/square-commands.js

@@ -1,15 +1,17 @@
 import { cmdActivity } from '../activity.js';
-import { formatActivityId, formatHardCap, parseActivityId, } from '../model.js';
-import { participantCommandPrefix, participantIdentity, quoteShell, renderEventCli, renderAmbientEvent, withPathOutput, } from '../presentation.js';
-import { claimSessionParticipant, hasAutomaticDeliveryIdentity, localSessionIdentities, lookupParticipant, readParticipantOwner, recordSessionDone, } from '../registry.js';
-import { createHostLedgerPort } from '../host-ledger-file-adapter.js';
-import { sessionIdsFromEnvironment } from '../square-projections.js';
-import { nowMs } from '../runtime.js';
+import { scanMentionCandidates } from '../mention-parse.js';
+import { validateDoneBody } from '../decisions.js';
+import { formatHardCap, } from '../model.js';
+import { formatRefusal, participantCommandPrefix, participantIdentity, takeoverRecoveryLines, renderRoomChangeText, renderAmbientEvent, withPathOutput, } from '../presentation.js';
+import { hostLedgerForEnv, hasAutomaticDeliveryIdentity, } from '../registry.js';
+import { actId, 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 { Square } from '../square-wiring.js';
+import { createSquareApplication } from '../square-application.js';
 import { entryPresentation, eventPresentation } from '../views.js';
 import { createDefaultWakeTransport } from '../notifications.js';
+import { style } from '../tty-style.js';
 import { fail, parseBoundedLimit, parseHardCap, parsePositiveInteger, readStdin, requireParticipant, requireSquarePath, requireValue, resolveBody, usage, } from './context.js';
 const JOIN_DEFAULT_LAST = 10;
 const JOIN_MAX_LAST = 100;
@@ -57,7 +59,7 @@ export const buildCommand = {
         await createSquare(squarePath, intent.options, snippet);
         const cap = intent.options.hardCap === null ? 'unlimited' : formatHardCap(intent.options.hardCap);
         const throttle = intent.options.throttlePerMinute === undefined ? [] : [`  · throttle ${intent.options.throttlePerMinute}/min`];
-        return withPathOutput(squarePath, ['✓ built', `  · cap ${cap}`, ...throttle, '  · participants (none seeded — first join adds names)'].join('\n'), { participantCount: 0 });
+        return withPathOutput(squarePath, ['✓ the square is open', `  · cap ${cap}`, ...throttle, '  · nobody here yet — the first join steps in'].join('\n'), { participantCount: 0 });
     },
     present: (result) => process.stdout.write(result),
 };
@@ -84,77 +86,60 @@ export const joinCommand = {
     parse: parseJoin,
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
-        const beforeSquare = await openSquare(squarePath, { clock: nowMs });
+        const hostLedger = hostLedgerForEnv(context.env);
+        const beforeSquare = await openSquare(squarePath, { clock: nowMs, env: context.env, hostLedger });
         const before = await entryPresentation(beforeSquare, intent.name, intent.lastN);
         await closeOpenSquare(beforeSquare);
-        const hostLedger = createHostLedgerPort();
-        const square = await Square.at({ path: squarePath, clock: nowMs, hostLedger, wakeTransport: await createDefaultWakeTransport(hostLedger, nowMs) });
+        const application = createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, participant: intent.name, clock: nowMs, hostLedger, wakeTransport: await createDefaultWakeTransport(hostLedger, nowMs) });
+        let joinedName;
+        let joinKind;
         try {
-            const identity = localSessionIdentities()[0];
-            const owner = before.joined ? await readParticipantOwner(squarePath, intent.name) : undefined;
-            const reconnect = before.joined && identity !== undefined && owner?.sessionId === identity.sessionId;
-            const isRejoin = before.joined;
-            if (isRejoin && !intent.kick && !reconnect) {
-                fail([
+            const result = await application.join({ takeover: intent.kick });
+            joinedName = result.participant;
+            joinKind = result.kind;
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'already_joined') {
+                process.stderr.write(formatRefusal(squarePath, [
                     `✕ ${participantIdentity(intent.name)} shoos you out of the square`,
-                    `  · a same-named participant stands here — the name is taken`,
-                    `  · --kick banishes her and the name becomes yours`,
-                    `» ${participantCommandPrefix(squarePath, intent.name)} join --kick`,
-                ].join('\n'));
-            }
-            const takeoverNeeded = isRejoin && intent.kick;
-            const oldBindings = takeoverNeeded ? await lookupParticipant(squarePath, intent.name) : [];
-            let participant;
-            if (takeoverNeeded) {
-                const currentSessions = new Set(sessionIdsFromEnvironment());
-                await square.takeover(intent.name);
-                for (const binding of oldBindings) {
-                    if (!currentSessions.has(binding.sessionId)) {
-                        await recordSessionDone(binding.sessionId, binding.name, binding.squarePath, binding.channel).catch(() => undefined);
-                    }
-                }
-                await claimSessionParticipant(squarePath, intent.name, process.env);
-                participant = await square.join(intent.name);
+                    '  · a same-named participant stands here — the name is taken',
+                    ...takeoverRecoveryLines(squarePath, intent.name),
+                ], { participantCount: before.participantCount }));
+                process.exit(2);
             }
-            else {
-                await claimSessionParticipant(squarePath, intent.name, process.env);
-                participant = await square.join(intent.name);
-            }
-            const joinedName = participant.name;
-            const afterSquare = await openSquare(squarePath, { clock: nowMs });
-            const after = await entryPresentation(afterSquare, joinedName, intent.lastN);
-            await closeOpenSquare(afterSquare);
-            await square.reconcileBinding().catch(() => undefined);
-            const activities = after.recentActivities.map((event) => renderAmbientEvent(event, joinedName, {
-                now: nowMs(),
-                preview: intent.lastN === null ? undefined : 200,
-                actNumber: event.kind === 'say' ? after.sayNumbers[event.index] : undefined,
-                squareState: after.state,
-            })).filter(Boolean).join('\n\n');
-            const contextText = after.joinContext;
-            const fallback = hasAutomaticDeliveryIdentity()
-                ? []
-                : ['', `» ${participantCommandPrefix(squarePath, joinedName)} catch --idle 30m`, '  no session delivery detected — keep this catch open for new activity'];
-            const scene = after.scene;
-            const entryLine = !isRejoin
-                ? '● You stepped into the square'
-                : reconnect && !intent.kick
-                    ? '● you are already in the square'
-                    : `✓ you banished the original ${participantIdentity(joinedName)} — the name is yours`;
-            const output = [
-                entryLine,
-                '',
-                "Don't treat Square as a public dumping ground. Speak here only when you genuinely think someone else needs to know; otherwise you are needlessly interrupting them.",
-                ...(reconnect || scene === '' ? [] : ['', scene]),
-                ...(isRejoin || contextText === '' ? [] : ['', 'context', contextText]),
-                ...(isRejoin || activities === '' ? [] : ['', 'recent activity', activities]),
-                ...fallback,
-            ].join('\n');
-            return withPathOutput(squarePath, output, { participantCount: after.participantCount });
-        }
-        finally {
-            await square.close();
+            throw error;
         }
+        const afterSquare = await openSquare(squarePath, { clock: nowMs, env: context.env, hostLedger });
+        const after = await entryPresentation(afterSquare, joinedName, intent.lastN);
+        await closeOpenSquare(afterSquare);
+        const activities = after.recentActivities.map((event) => renderAmbientEvent(event, joinedName, {
+            now: nowMs(),
+            preview: intent.lastN === null ? undefined : 200,
+            actNumber: event.kind === 'say' ? after.sayNumbers[event.index] : undefined,
+            squareState: after.state,
+        })).filter(Boolean).join('\n\n');
+        const contextText = after.joinContext;
+        const fallback = hasAutomaticDeliveryIdentity()
+            ? []
+            : ['', `${participantCommandPrefix(squarePath, joinedName)} catch --idle 30m`, '  the square has no way to call you — keep this catch open and stay within earshot'];
+        const scene = after.scene;
+        const entryLine = joinKind === 'joined'
+            ? '● you stepped into the square'
+            : joinKind === 'reconnected'
+                ? '● you are already in the square'
+                : `✓ you banished the original ${participantIdentity(joinedName)} — the name is yours`;
+        const isRejoin = joinKind !== 'joined';
+        const reconnect = joinKind === 'reconnected';
+        const output = [
+            entryLine,
+            '',
+            "· carved into the fountain's edge: every word here lands on a real ear — speak when someone needs it.",
+            ...(reconnect || scene === '' ? [] : ['', scene]),
+            ...(isRejoin || contextText === '' ? [] : ['', style('dim', 'context'), contextText]),
+            ...(isRejoin || activities === '' ? [] : ['', style('dim', 'recent activity'), activities]),
+            ...fallback,
+        ].join('\n');
+        return withPathOutput(squarePath, output, { participantCount: after.participantCount });
     },
     present: (result) => process.stdout.write(result),
 };
@@ -173,20 +158,17 @@ function parseActivity(argv, context) {
         else if (argument === '--no-wait')
             noWait = true;
         else if (argument === '--beside')
-            fail('✕ express does not know --beside\n» square express --help');
+            fail('✕ express does not know --beside\nsquare express --help');
         else if (argument === '--bell')
             bell = true;
         else if (argument === '--no-mention')
             noMention = true;
         else if (argument === '--mention') {
-            mentions.push(requireParticipant(requireValue(argv, index, argument)));
+            mentions.push(requireValue(argv, index, argument));
             index += 1;
         }
         else if (argument === '--reply') {
-            const replyIndex = parseActivityId(requireValue(argv, index, argument));
-            if (replyIndex === undefined)
-                fail('Invalid --reply: expected an activity id like act/12');
-            reply = replyIndex;
+            reply = requireValue(argv, index, argument);
             index += 1;
         }
         else
@@ -194,11 +176,9 @@ function parseActivity(argv, context) {
     }
     const reach = bell ? 'bell' : undefined;
     if (bell && (noMention || mentions.length > 0))
-        fail('✕ --bell cannot be combined with --mention or --no-mention\n» square express --help');
+        fail('✕ --bell cannot be combined with --mention or --no-mention\nsquare express --help');
     if (noMention && mentions.length > 0)
-        fail('✕ --no-mention cannot be combined with --mention\n» square express --help');
-    if (!bell && !noMention && mentions.length === 0)
-        fail('✕ express needs --mention <name>, --no-mention, or --bell\n» square express --help');
+        fail('✕ --no-mention cannot be combined with --mention\nsquare express --help');
     if (bodyArgs.length !== 1) {
         if (bodyArgs.length === 0) {
             if (!process.stdin.isTTY)
@@ -213,14 +193,18 @@ export const expressCommand = {
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
         const body = await resolveBody(intent.activity);
-        const reachArg = intent.reach === 'bell' ? ' --bell' : intent.noMention ? ' --no-mention' : intent.mentions.map((name) => ` --mention ${quoteShell(name)}`).join('');
+        if (intent.reach === undefined && !intent.noMention && intent.mentions.length === 0 && scanMentionCandidates(body).length === 0) {
+            fail('✕ express needs --mention <name>, --no-mention, --bell, or an @name in the body\nsquare express --help');
+        }
         await cmdActivity(squarePath, intent.name, body, (value) => value, {
             force: intent.force,
             noWait: intent.noWait,
+            noMention: intent.noMention,
             mentions: intent.mentions,
             reach: intent.reach,
             reply: intent.reply,
-            forceCommand: `${participantCommandPrefix(squarePath, intent.name)} express --force${reachArg}${intent.reply === undefined ? '' : ` --reply ${formatActivityId(intent.reply)}`} -`,
+            cwd: context.cwd,
+            env: context.env,
         });
     },
     present: () => { },
@@ -247,15 +231,12 @@ export const listenCommand = {
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
         const square = await Square.at({ path: squarePath, clock: nowMs });
-        const facade = await openParticipant({ path: squarePath, clock: nowMs }, intent.name);
         try {
-            const participant = facade.participant;
-            const result = await participant.listen(intent.target);
+            const result = await createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, participant: intent.name, clock: nowMs }).listen(intent.target);
             const participantCount = (await square.snapshot()).participants.filter((item) => item.state === 'joined').length;
-            return listenerPresentation(squarePath, participant.name, intent.target, 'listen', result.activity, participantCount);
+            return listenerPresentation(squarePath, intent.name, intent.target, 'listen', result.activity, participantCount);
         }
         finally {
-            await facade.close();
             await square.close();
         }
     },
@@ -266,15 +247,12 @@ export const ignoreCommand = {
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
         const square = await Square.at({ path: squarePath, clock: nowMs });
-        const facade = await openParticipant({ path: squarePath, clock: nowMs }, intent.name);
         try {
-            const participant = facade.participant;
-            const result = await participant.ignore(intent.target);
+            const result = await createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, participant: intent.name, clock: nowMs }).ignore(intent.target);
             const participantCount = (await square.snapshot()).participants.filter((item) => item.state === 'joined').length;
-            return listenerPresentation(squarePath, participant.name, intent.target, 'ignore', result.activity, participantCount);
+            return listenerPresentation(squarePath, intent.name, intent.target, 'ignore', result.activity, participantCount);
         }
         finally {
-            await facade.close();
             await square.close();
         }
     },
@@ -285,10 +263,9 @@ export const listeningCommand = {
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
         const square = await Square.at({ path: squarePath, clock: nowMs });
-        const facade = await openParticipant({ path: squarePath, clock: nowMs }, intent.name);
         try {
-            const participant = facade.participant;
-            const targets = await participant.listening();
+            const participant = { name: intent.name };
+            const targets = await createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, participant: intent.name, clock: nowMs }).listening();
             const participantCount = (await square.snapshot()).participants.filter((item) => item.state === 'joined').length;
             const body = targets.length === 0
                 ? `○ ${participantIdentity(participant.name)} is not turned toward anyone`
@@ -296,31 +273,38 @@ export const listeningCommand = {
             return withPathOutput(squarePath, body, { participantCount });
         }
         finally {
-            await facade.close();
             await square.close();
         }
     },
     present: (result) => process.stdout.write(result),
 };
+function validateDoneInput(body) {
+    try {
+        validateDoneBody(body);
+    }
+    catch (error) {
+        fail(`${error instanceof Error ? error.message : String(error)}\nsquare done --help`);
+    }
+}
 function parseDone(argv, context) {
     if (argv.length > 1)
         usage(context.command);
+    if (argv[0] !== '-')
+        validateDoneInput(argv[0]);
     return { name: requireParticipant(context.name), body: argv.length === 1 ? argv[0] : undefined };
 }
 export const doneCommand = {
     parse: parseDone,
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
-        const body = (await resolveBody(intent.body ?? (process.stdin.isTTY ? '' : '-'))).replace(/\r\n/g, '\n').trim();
-        const square = await Square.at({ path: squarePath, clock: nowMs });
-        const participant = await square.join(intent.name);
-        const result = await participant.done(body);
-        await square.reconcileBinding();
-        await square.close();
+        const body = intent.body === '-' || !process.stdin.isTTY ? await readStdin() : '';
+        validateDoneInput(body);
+        const application = createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, clock: nowMs, participant: intent.name });
+        const result = await application.done(body);
         const name = result.activity.actor;
-        const presentation = await openSquare(squarePath, { clock: nowMs });
+        const presentation = await openSquare(squarePath, { clock: nowMs, env: context.env, hostLedger: hostLedgerForEnv(context.env) });
         const participantCount = (await entryPresentation(presentation, name).finally(() => closeOpenSquare(presentation))).participantCount;
-        return withPathOutput(squarePath, `○ ${participantIdentity(name)} steps out of the square — done · just now`, { participantCount });
+        return withPathOutput(squarePath, `○ ${participantIdentity(name)} steps out of the square — done · ${result.activity.id} · just now`, { participantCount });
     },
     present: (result) => process.stdout.write(result),
 };
@@ -333,19 +317,12 @@ export const holdCommand = {
     parse: parseHold,
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
-        const square = await Square.at({ path: squarePath, clock: nowMs });
-        try {
-            const participant = await square.join(intent.name);
-            const result = await participant.hold((await resolveBody(intent.body ?? '')).replace(/\r\n/g, '\n').trim());
-            await square.close();
-            const presentationSquare = await openSquare(squarePath, { clock: nowMs });
-            const presentation = await eventPresentation(presentationSquare, result.activity.id);
-            await closeOpenSquare(presentationSquare);
-            return withPathOutput(squarePath, renderEventCli(presentation.activity), { participantCount: presentation.participantCount, held: true });
-        }
-        finally {
-            await square.close();
-        }
+        const application = createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, clock: nowMs, participant: intent.name });
+        const result = await application.hold((await resolveBody(intent.body ?? '')).replace(/\r\n/g, '\n').trim());
+        const presentationSquare = await openSquare(squarePath, { clock: nowMs, env: context.env, hostLedger: hostLedgerForEnv(context.env) });
+        const presentation = await eventPresentation(presentationSquare, result.activity.id);
+        await closeOpenSquare(presentationSquare);
+        return withPathOutput(squarePath, `· ${renderRoomChangeText(presentation.activity)} · ${actId(presentation.activity.index)} · just now`, { participantCount: presentation.participantCount, held: true });
     },
     present: (result) => process.stdout.write(result),
 };
@@ -357,19 +334,12 @@ export const resumeCommand = {
     },
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
-        const square = await Square.at({ path: squarePath, clock: nowMs });
-        try {
-            const participant = await square.join(intent.name);
-            const result = await participant.resume();
-            await square.close();
-            const presentationSquare = await openSquare(squarePath, { clock: nowMs });
-            const presentation = await eventPresentation(presentationSquare, result.activity.id);
-            await closeOpenSquare(presentationSquare);
-            return withPathOutput(squarePath, renderEventCli(presentation.activity), { participantCount: presentation.participantCount });
-        }
-        finally {
-            await square.close();
-        }
+        const application = createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, clock: nowMs, participant: intent.name });
+        const result = await application.resume();
+        const presentationSquare = await openSquare(squarePath, { clock: nowMs, env: context.env, hostLedger: hostLedgerForEnv(context.env) });
+        const presentation = await eventPresentation(presentationSquare, result.activity.id);
+        await closeOpenSquare(presentationSquare);
+        return withPathOutput(squarePath, `✓ ${renderRoomChangeText(presentation.activity)} · ${actId(presentation.activity.index)} · just now`, { participantCount: presentation.participantCount });
     },
     present: (result) => process.stdout.write(result),
 };

package/dist/decisions.d.ts

@@ -58,6 +58,8 @@ export type ActDecision = {
     type: 'bell_quota';
     nextAt: number;
 };
+/** The unread activity a viewer has not caught up to, grouped by speaker. */
+export declare function unreadActivitySummaries(squareState: SquareState, name: string, now: number): UnreadActivitySummary[];
 export declare function decideAct(squareState: SquareState, input: {
     name: string;
     body: string;
@@ -66,7 +68,9 @@ export declare function decideAct(squareState: SquareState, input: {
     mentions?: readonly string[];
     reach?: Reach;
     reply?: number;
+    noMention?: boolean;
 }): ActDecision;
+export declare function validateDoneBody(body: unknown): void;
 export declare function coreDone(squareState: SquareState, name: string, body: string, now: number): Extract<Act, {
     kind: 'done';
 }>;

package/dist/decisions.js

@@ -1,15 +1,16 @@
 import { SquareError, sameName, validateName, } from './model.js';
 import { participantIdentity } from './participant-identity.js';
-import { UNREAD_BLOCK_GRACE_MS, actId, actStableIndex, foldedState, freshWatchLease, publicActs, resolveRosterName, THROTTLE_WINDOW_MS, } from './runtime.js';
+import { UNREAD_BLOCK_GRACE_MS, actId, actStableIndex, foldedState, freshWatchLease, publicActs, resolveRosterName, rosterNames, THROTTLE_WINDOW_MS, } from './runtime.js';
 import { actDelta, directedPeerSays } from './activity-feed.js';
 import { formatActivityId, isIgnored, isListening, listeningTo, MAX_IDENTITY_SET_SIZE, validate } from './square-core.js';
 import { deriveDeliveryModel } from './delivery.js';
 import { compileSearchPattern } from './search.js';
+import { scanMentionCandidates, resolveNameAt } from './mention-parse.js';
 export function resolveKnownName(squareState, name) {
     validateName(name);
     const known = resolveRosterName(squareState, name);
     if (known === undefined) {
-        throw new SquareError('invalid_args', `Unknown participant "${participantIdentity(name)}".`);
+        throw new SquareError('invalid_args', `✕ ${participantIdentity(name)} has never stepped into this square`);
     }
     return known;
 }
@@ -66,6 +67,40 @@ function requireStanding(squareState, act) {
     throw new Error(`Unexpected standing validation result: ${result.reason}`);
 }
 const UNREAD_PREVIEW_LIMIT = 3;
+/** The unread activity a viewer has not caught up to, grouped by speaker. */
+export function unreadActivitySummaries(squareState, name, now) {
+    const delivery = deriveDeliveryModel(squareState);
+    const delta = actDelta(squareState.acts, delivery.cursorFor(name));
+    const unreadPublic = directedPeerSays(squareState, delta, name, delivery);
+    const sayCountByActor = new Map();
+    const unreadByParticipant = new Map();
+    for (const item of unreadPublic) {
+        if (item.kind === 'say') {
+            const key = item.actor.toLocaleLowerCase();
+            sayCountByActor.set(key, (sayCountByActor.get(key) ?? 0) + 1);
+        }
+        if (sameName(item.actor, name))
+            continue;
+        const actorKey = item.actor.toLocaleLowerCase();
+        const currentSummary = unreadByParticipant.get(item.actor);
+        unreadByParticipant.set(item.actor, {
+            count: (currentSummary?.count ?? 0) + 1,
+            latestAt: currentSummary === undefined ? item.at : Math.max(currentSummary.latestAt, item.at),
+            previews: [
+                ...(currentSummary?.previews ?? []),
+                { number: sayCountByActor.get(actorKey) ?? 1, act: item, perception: delivery.perceive(item, name) },
+            ].slice(-UNREAD_PREVIEW_LIMIT),
+        });
+    }
+    return [...unreadByParticipant.entries()]
+        .map(([participant, summary]) => ({
+        name: participant,
+        count: summary.count,
+        latestActivityAgeMs: Math.max(0, now - summary.latestAt),
+        previews: summary.previews,
+    }))
+        .sort((a, b) => a.latestActivityAgeMs - b.latestActivityAgeMs || a.name.localeCompare(b.name));
+}
 export function decideAct(squareState, input) {
     const { now, force } = input;
     const name = resolveStandingName(squareState, input.name);
@@ -81,7 +116,7 @@ export function decideAct(squareState, input) {
         validateName(requested);
         const resolved = joinedNames.find((candidate) => sameName(candidate, requested));
         if (resolved === undefined) {
-            throw new SquareError('invalid_args', `Unknown mention target ${participantIdentity(requested)}.`);
+            throw new SquareError('invalid_args', `✕ ${participantIdentity(requested)} is not standing in this square`);
         }
         if (!mentionNames.some((existing) => sameName(existing, resolved))) {
             if (mentionNames.length >= MAX_IDENTITY_SET_SIZE) {
@@ -90,8 +125,42 @@ export function decideAct(squareState, input) {
             mentionNames.push(resolved);
         }
     }
+    if (input.noMention !== true) {
+        // Body @name tokens resolve against the standing roster at landing time; the stored
+        // body never changes, only mention metadata is derived. Explicit --no-mention turns
+        // this scan off entirely.
+        const unmatched = [];
+        for (const candidate of scanMentionCandidates(body)) {
+            const resolved = resolveNameAt(body, candidate, joinedNames);
+            if (resolved === undefined) {
+                unmatched.push(candidate);
+                continue;
+            }
+            if (!mentionNames.some((existing) => sameName(existing, resolved))) {
+                if (mentionNames.length >= MAX_IDENTITY_SET_SIZE) {
+                    throw new SquareError('invalid_args', `An activity can mention at most ${MAX_IDENTITY_SET_SIZE} participants`);
+                }
+                mentionNames.push(resolved);
+            }
+        }
+        // A bell already reaches everyone: only there does an unmatched @token stay literal text.
+        if (reach !== 'bell' && unmatched.length > 0) {
+            const roster = rosterNames(squareState);
+            const notStanding = unmatched.filter((candidate) => resolveNameAt(body, candidate, roster) !== undefined);
+            const unknown = unmatched.filter((candidate) => !notStanding.includes(candidate));
+            const lines = [];
+            if (unknown.length > 0) {
+                lines.push(`✕ ${unknown.map((candidate) => participantIdentity(candidate.token)).join(', ')} ${unknown.length === 1 ? 'does' : 'do'} not match anyone in this square`);
+            }
+            if (notStanding.length > 0) {
+                lines.push(`✕ ${notStanding.map((candidate) => participantIdentity(candidate.token)).join(', ')} ${notStanding.length === 1 ? 'is' : 'are'} not standing in this square`);
+            }
+            lines.push('  · wrap literal @text in backticks, or pass --no-mention to land bare');
+            throw new SquareError('invalid_args', lines.join('\n'));
+        }
+    }
     if (reach === 'bell' && mentionNames.length > 0) {
-        throw new SquareError('invalid_args', 'A bell cannot be combined with --mention.');
+        throw new SquareError('invalid_args', 'A bell cannot be combined with a mention — remove --mention or the @name in the body.');
     }
     const reply = input.reply;
     if (reply !== undefined) {
@@ -126,34 +195,7 @@ export function decideAct(squareState, input) {
     const delta = actDelta(squareState.acts, delivery.cursorFor(name));
     const unreadPublic = directedPeerSays(squareState, delta, name, delivery);
     const unreadRoomChanges = [];
-    const sayCountByActor = new Map();
-    const unreadByParticipant = new Map();
-    for (const item of unreadPublic) {
-        if (item.kind === 'say') {
-            const key = item.actor.toLocaleLowerCase();
-            sayCountByActor.set(key, (sayCountByActor.get(key) ?? 0) + 1);
-        }
-        if (sameName(item.actor, name))
-            continue;
-        const actorKey = item.actor.toLocaleLowerCase();
-        const currentSummary = unreadByParticipant.get(item.actor);
-        unreadByParticipant.set(item.actor, {
-            count: (currentSummary?.count ?? 0) + 1,
-            latestAt: currentSummary === undefined ? item.at : Math.max(currentSummary.latestAt, item.at),
-            previews: [
-                ...(currentSummary?.previews ?? []),
-                { number: sayCountByActor.get(actorKey) ?? 1, act: item, perception: delivery.perceive(item, name) },
-            ].slice(-UNREAD_PREVIEW_LIMIT),
-        });
-    }
-    const activitySummaries = [...unreadByParticipant.entries()]
-        .map(([participant, summary]) => ({
-        name: participant,
-        count: summary.count,
-        latestActivityAgeMs: Math.max(0, now - summary.latestAt),
-        previews: summary.previews,
-    }))
-        .sort((a, b) => a.latestActivityAgeMs - b.latestActivityAgeMs || a.name.localeCompare(b.name));
+    const activitySummaries = unreadActivitySummaries(squareState, name, now);
     const latestActivityAgeMs = activitySummaries[0]?.latestActivityAgeMs;
     const hasUnread = unreadPublic.length > 0;
     const hasFreshUnreadActivity = latestActivityAgeMs !== undefined && latestActivityAgeMs <= UNREAD_BLOCK_GRACE_MS;
@@ -168,15 +210,21 @@ export function decideAct(squareState, input) {
             ...(reach !== undefined ? { reach } : {}),
             ...(reply !== undefined ? { reply } : {}),
         },
-        confirmation: `● heads turn your way — #${ownActCount}`,
+        confirmation: `● your activity lands — #${ownActCount}`,
         ownActCount,
         pendingPublic: unreadPublic,
         pendingRoomChanges: unreadRoomChanges,
     };
 }
+export function validateDoneBody(body) {
+    if (body !== undefined && body !== '') {
+        throw new SquareError('invalid_args', 'done only leaves the square and does not accept a message; use express before leaving');
+    }
+}
 export function coreDone(squareState, name, body, now) {
+    validateDoneBody(body);
     const resolvedName = resolveStandingName(squareState, name);
-    const act = { kind: 'done', actor: resolvedName, at: now, body: body.replace(/\r\n/g, '\n').trim() };
+    const act = { kind: 'done', actor: resolvedName, at: now };
     requireStanding(squareState, act);
     return act;
 }

package/dist/delivery-operations.d.ts

@@ -1,9 +1,8 @@
 import { type SquareState } from './model.js';
-import type { HostLedgerPort, PresenceRecord, PresentationEvidenceProjection, SquareArtifactPort, DeliverPendingInput, DeliveryResult, ObserveSquareInput, ReconcileBindingInput, SquareObservation } from './ports.js';
+import type { HostLedgerPort, PresenceRecord, PresentationEvidenceProjection, SquareArtifactPort, DeliverPendingInput, DeliveryResult, ObserveSquareInput, SquareObservation } from './ports.js';
 import { deriveDeliveryModel } from './delivery.js';
 import { type WakeAttempt } from './square-projections.js';
 export declare function observeSquare(input: ObserveSquareInput): Promise<SquareObservation>;
-export declare function reconcileBinding(input: ReconcileBindingInput): Promise<import("./host-ledger.js").ReconcileBindingResult>;
 export declare function deliverPending(input: DeliverPendingInput): Promise<DeliveryResult>;
 export declare function selectPendingWakeActivities(state: SquareState, routes: readonly PresenceRecord[], attempts: readonly WakeAttempt[], now: number, graceMs: number, limit: number, delivery?: import("./delivery.js").DeliveryModel, presentations?: readonly PresentationEvidenceProjection[]): number[];
 export declare function sweepPending(input: {

package/dist/delivery-operations.js

@@ -39,7 +39,7 @@ export async function observeSquare(input) {
     let rows = [];
     if (input.hostLedger !== undefined) {
         try {
-            rows = await input.hostLedger.listPresence({ location: input.location, scopes: ['user', 'local'], now: input.now });
+            rows = await input.hostLedger.listPresence({ location: input.location, now: input.now });
         }
         catch {
             rows = [];
@@ -55,9 +55,6 @@ export async function observeSquare(input) {
     }));
     return { ...(input.location === undefined ? {} : { location: input.location }), version: snapshot.version, state: snapshot.state, pending: delivery.joinedRecipients().map((recipient) => ({ recipient, notifications: delivery.pendingFor(recipient) })), bindings };
 }
-export async function reconcileBinding(input) {
-    return input.hostLedger.reconcileBinding({ artifact: input.artifact, scopes: input.scopes, now: input.now });
-}
 export async function deliverPending(input) {
     const observation = await observeSquare({ artifact: input.artifact, hostLedger: input.hostLedger, location: input.location, now: input.now });
     const routes = (observation.state.routes ?? []).map((route) => ({

package/dist/file-changes.d.ts

@@ -0,0 +1,12 @@
+export declare function canonicalFilePath(value: string): Promise<string>;
+export interface VersionObserver<T> {
+    readonly generation: number;
+    hinted(since: number, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
+    read(signal?: AbortSignal): Promise<T>;
+    changed(since: T, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
+    close(): void;
+}
+/** Shared only within this process. Durable state is always read at the storage boundary. */
+export declare function observeFileVersion<T>(filePath: string, kind: string, read: (file: string, signal: AbortSignal) => Promise<T>): Promise<VersionObserver<T>>;
+/** File metadata invalidates a ledger projection; it is not presentation evidence. */
+export declare function observeFileMetadata(file: string): Promise<VersionObserver<string>>;