@astrosheep/square 0.3.58 → 0.3.62

package/dist/cli/observation-commands.js

@@ -6,15 +6,20 @@ import { cmdListSquares } from '../list.js';
 import { nameKey, parseActivityId, sameName } from '../model.js';
 import { commandPrefix, participantIdentity, renderGrepActivitiesView, renderEventCli, renderAmbientEvent, renderPresenceAnchor, truncateChars, withPathOutput, quoteShell, } from '../presentation.js';
 import { actId, nowMs } from '../runtime.js';
+import { style } from '../tty-style.js';
 import { cmdStream, cmdStreamNdjson } from '../stream.js';
 import { formatRelativeTime, formatTimestamp, parseTimeOrRelative } from '../time.js';
 import { cmdWatch } from '../watch.js';
 import { openSquare } from '../square-file-adapter.js';
 import { closeOpenSquare } from '../open-square.js';
-import { historyPresentation, participantsPresentation, statusPresentation } from '../views.js';
+import { createSquareApplication } from '../square-application.js';
+import { historyPresentation } from '../views.js';
+import { hostLedgerForEnv } from '../registry.js';
 import { fail, parseBoundedLimit, parseDurationMs, parseNameList, parseNonNegativeInteger, readStdin, requireParticipant, requireSquarePath, requireValue, usage, } from './context.js';
 import { CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT } from '../catch-decisions.js';
 const STATUS_PARTICIPANT_PREVIEW_LIMIT = 10;
+/** A participant counts as here when their last sign of life sits inside this window. */
+const STATUS_HERE_WINDOW_MS = 30 * 60_000;
 const HISTORY_DEFAULT_LIMIT = 10;
 const HISTORY_MAX_LIMIT = 100;
 const PARTICIPANTS_DEFAULT_LIMIT = 20;
@@ -94,10 +99,10 @@ export const catchCommand = {
         for (let index = 0; index < argv.length; index++) {
             if (argv[index] === '--id') {
                 if (id !== undefined)
-                    fail('✕ catch accepts one --id\n» square catch --help');
+                    fail('✕ catch accepts one --id\nsquare catch --help');
                 const value = requireValue(argv, index, '--id');
                 if (parseActivityId(value) === undefined)
-                    fail('✕ invalid --id: expected an activity id like act/12\n» square catch --help');
+                    fail('✕ invalid --id: expected an activity id like act/12\nsquare catch --help');
                 id = value;
                 index += 1;
             }
@@ -121,11 +126,11 @@ export const catchCommand = {
             else if (argv[index] === '--now')
                 now = true;
             else
-                fail(`✕ catch does not know ${argv[index]}\n» square catch --help`);
+                fail(`✕ catch does not know ${argv[index]}\nsquare catch --help`);
         }
         if (id !== undefined) {
             if (argv.some((flag) => ['--idle', '--from', '--mention', '--limit', '--replace'].includes(flag))) {
-                fail('✕ --id cannot be combined with --idle, --from, --mention, --limit or --replace\n» square catch --help');
+                fail('✕ --id cannot be combined with --idle, --from, --mention, --limit or --replace\nsquare catch --help');
             }
             return { id, now: true };
         }
@@ -144,7 +149,7 @@ export const catchCommand = {
     },
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
-        const caught = await cmdWatch(squarePath, requireParticipant(context.name), intent);
+        const caught = await cmdWatch(squarePath, requireParticipant(context.name), intent, { cwd: context.cwd, env: context.env });
         if (caught !== false)
             await sweepPendingNotifications(squarePath);
     },
@@ -271,7 +276,7 @@ function parseHistory(argv, context) {
         else if (flag === '--json')
             json = true;
         else
-            fail(`✕ history does not know ${flag}\n» square history --help`);
+            fail(`✕ history does not know ${flag}\nsquare history --help`);
     }
     if (grep !== undefined && fixed !== undefined)
         fail('--grep and --fixed cannot be combined.');
@@ -300,6 +305,30 @@ function parseHistory(argv, context) {
         continuationArgs: historyContinuationArgs(argv),
     };
 }
+function applicationHistoryQuery(options) {
+    return {
+        ...(options.participants === undefined || options.participants.length === 0 ? {} : { from: options.participants }),
+        ...(options.mention === undefined ? {} : { mention: options.mention }),
+        ...(options.afterIndex === undefined ? {} : { after: actId(options.afterIndex) }),
+        ...(options.beforeIndex === undefined ? {} : { before: actId(options.beforeIndex) }),
+        ...(options.grep === undefined ? {} : { grep: options.grep }), ...(options.fixed === undefined ? {} : { fixed: options.fixed }),
+        order: 'asc',
+    };
+}
+function activityAsStored(activity) {
+    const index = parseActivityId(activity.id);
+    if (index === undefined)
+        throw new Error('Application returned a non-canonical activity id');
+    switch (activity.kind) {
+        case 'say': return { index, kind: 'say', actor: activity.actor, at: activity.at, body: activity.body ?? '', mentions: activity.mentions, ...(activity.reach === undefined ? {} : { reach: activity.reach }), ...(activity.reply === undefined ? {} : { reply: parseActivityId(activity.reply) ?? undefined }) };
+        case 'done': return { index, kind: 'done', actor: activity.actor, at: activity.at, body: activity.body ?? '' };
+        case 'hold': return { index, kind: 'hold', actor: activity.actor, at: activity.at, ...(activity.body === undefined ? {} : { body: activity.body }) };
+        case 'resume': return { index, kind: 'resume', actor: activity.actor, at: activity.at };
+        case 'join': return { index, kind: 'join', actor: activity.actor, at: activity.at };
+        case 'listen': return { index, kind: 'listen', actor: activity.actor, target: activity.target ?? '', at: activity.at };
+        case 'ignore': return { index, kind: 'ignore', actor: activity.actor, target: activity.target ?? '', at: activity.at };
+    }
+}
 function historyContinuationCommand(options, squarePath, direction, index) {
     const args = [...(options.continuationArgs ?? []), direction, actId(index), '--limit', String(options.lastN ?? HISTORY_DEFAULT_LIMIT)];
     return `${commandPrefix(squarePath)} history ${args.map((arg) => arg.startsWith('-') || /^act\/\d+$/.test(arg) || /^\d+$/.test(arg) ? arg : quoteShell(arg)).join(' ')}`;
@@ -308,6 +337,10 @@ function boundedHistoryCommand(options, squarePath) {
     const args = [...(options.continuationArgs ?? []), '--limit', String(HISTORY_MAX_LIMIT)];
     return `${commandPrefix(squarePath)} history ${args.map((arg) => arg.startsWith('-') || /^act\/\d+$/.test(arg) || /^\d+$/.test(arg) ? arg : quoteShell(arg)).join(' ')}`;
 }
+/** The archive-visible activity model: content plus the lifecycle moves that keep its story honest — a raised hand pairs with its lowering, and a departure pairs with the return. */
+function isArchiveActivity(item) {
+    return item.kind === 'say' || item.kind === 'done' || item.kind === 'hold' || item.kind === 'resume' || item.kind === 'join';
+}
 function renderFields(sayNumbers, item, fields) {
     return fields.map((field) => {
         switch (field) {
@@ -341,7 +374,7 @@ function jsonLine(sayNumbers, item) {
     });
 }
 function renderHistoryProjection(projection, visible, noTruncate, squarePath) {
-    const shown = visible.filter((activity) => activity.kind === 'say' || activity.kind === 'done');
+    const shown = visible.filter(isArchiveActivity);
     const preview = noTruncate || shown.length <= 1 ? undefined : 200;
     const chunks = [];
     for (const activity of shown) {
@@ -359,7 +392,7 @@ function renderHistoryProjection(projection, visible, noTruncate, squarePath) {
     if (chunks.length === 0)
         return 'latest\n  ○ no public activity in this view';
     if (preview !== undefined && shown.some((activity) => activity.kind === 'say' && activity.body.length > preview)) {
-        chunks.push(`» ${commandPrefix(squarePath)} history --no-truncate`);
+        chunks.push(`${commandPrefix(squarePath)} history --no-truncate`);
     }
     return chunks.join('\n\n');
 }
@@ -367,14 +400,18 @@ export const historyCommand = {
     parse(argv, context) { return parseHistory(argv, context); },
     async execute(options, context) {
         const squarePath = requireSquarePath(context);
-        const square = await openSquare(squarePath, { clock: nowMs });
+        const square = await openSquare(squarePath, { clock: nowMs, env: context.env, hostLedger: hostLedgerForEnv(context.env) });
         try {
             // Keep the projection chronological; pagination chooses a stable edge,
             // then --order only changes how the selected page is displayed.
             const projection = await historyPresentation(square, { ...options, order: 'asc' });
-            let events = [...projection.activities];
+            const useApplicationHistory = options.atIndexes === undefined && options.beforeContext === undefined && options.afterContext === undefined && options.after === undefined;
+            const applicationHistory = useApplicationHistory
+                ? await createSquareApplication({ cwd: context.cwd, env: { ...context.env, SQUARE_PARTICIPANT_NAME: undefined }, squarePath, clock: nowMs }).history(applicationHistoryQuery(options))
+                : undefined;
+            let events = applicationHistory === undefined ? [...projection.activities] : applicationHistory.map(activityAsStored);
             if (options.lastN === null && events.length > HISTORY_MAX_LIMIT) {
-                fail(`✕ history is capped at ${HISTORY_MAX_LIMIT} activities\n» ${boundedHistoryCommand(options, squarePath)}`);
+                fail(`✕ history is capped at ${HISTORY_MAX_LIMIT} activities\n${boundedHistoryCommand(options, squarePath)}`);
             }
             const searching = options.grep !== undefined || options.fixed !== undefined;
             const totalMatches = searching ? events.length : 0;
@@ -394,8 +431,8 @@ export const historyCommand = {
             const output = pattern === undefined || pattern === ''
                 ? renderHistoryProjection(projection, events, options.noTruncate === true, squarePath)
                 : renderGrepActivitiesView(events, totalMatches, options.noTruncate, squarePath, pattern, options.fixed !== undefined, () => 'full');
-            const publicEvents = events.filter((item) => item.kind === 'say' || item.kind === 'done');
-            const allPublic = projection.activities.filter((item) => item.kind === 'say' || item.kind === 'done');
+            const publicEvents = events.filter(isArchiveActivity);
+            const allPublic = projection.activities.filter(isArchiveActivity);
             const pageMin = publicEvents.length === 0 ? undefined : Math.min(...publicEvents.map((item) => item.index));
             const pageMax = publicEvents.length === 0 ? undefined : Math.max(...publicEvents.map((item) => item.index));
             const hasMore = options.lastN != null && publicEvents.length > 0 && (options.afterIndex !== undefined
@@ -403,7 +440,7 @@ export const historyCommand = {
                 : allPublic.some((item) => item.index < (pageMin ?? Infinity)));
             const cursorDirection = options.afterIndex !== undefined ? '--after' : '--before';
             const cursorIndex = cursorDirection === '--after' ? Math.max(...publicEvents.map((item) => item.index)) : Math.min(...publicEvents.map((item) => item.index));
-            const continuation = hasMore ? `\n\n» ${historyContinuationCommand(options, squarePath, cursorDirection, cursorIndex)}` : '';
+            const continuation = hasMore ? `\n\n${historyContinuationCommand(options, squarePath, cursorDirection, cursorIndex)}` : '';
             return withPathOutput(squarePath, output + continuation, { participantCount: projection.participantCount });
         }
         finally {
@@ -429,32 +466,30 @@ export const participantsCommand = {
     parse(argv, context) { return parseParticipants(argv, context); },
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
-        const square = await openSquare(squarePath, { clock: nowMs });
-        try {
+        const application = createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, clock: nowMs });
+        {
             const now = nowMs();
-            const participants = await participantsPresentation(square);
+            const participants = await application.participants();
             const lines = participants.slice(0, intent.limit).map((participant) => {
-                const glyph = participant.state === 'done' ? '○' : participant.presence === 'watching' ? '◎' : participant.activityCount > 0 ? '●' : '○';
+                const recent = participant.lastActiveAt !== undefined && now - participant.lastActiveAt <= STATUS_HERE_WINDOW_MS;
+                const glyph = participant.state === 'done' ? '○' : participant.presence === 'watching' ? '◎' : participant.activityCount > 0 && recent ? '●' : '○';
                 const state = participant.state === 'done' ? 'done' : participant.presence === 'watching' ? 'catching' : participant.state;
                 const last = participant.lastActiveAt === undefined ? '—' : formatRelativeTime(participant.lastActiveAt, now);
-                return `  ${glyph} ${participant.name} · ${state} · ${participant.activityCount} ${participant.activityCount === 1 ? 'activity' : 'activities'} · ${last}`;
+                return `  ${glyph} ${participant.name}${style('dim', ` · ${state} · ${participant.activityCount} ${participant.activityCount === 1 ? 'activity' : 'activities'} · ${last}`)}`;
             });
             const participantCount = participants.filter((participant) => participant.state === 'active').length;
             const tail = participants.length <= intent.limit
                 ? []
                 : [
-                    `  ○ ${lines.length} of ${participants.length} participants shown`,
+                    style('dim', `  ○ ${lines.length} of ${participants.length} participants shown`),
                     ...(participants.length <= PARTICIPANTS_MAX_LIMIT ? [
-                        `» ${participantsLimitCommand(squarePath, participants.length)}`,
+                        `${participantsLimitCommand(squarePath, participants.length)}`,
                     ] : []),
                 ];
             return withPathOutput(squarePath, ['participants', ...lines, ...tail].join('\n'), {
                 participantCount,
             });
         }
-        finally {
-            await closeOpenSquare(square);
-        }
     },
     present: (result) => process.stdout.write(result),
 };
@@ -463,41 +498,60 @@ export const statusCommand = {
         usage(context.command); return undefined; },
     async execute(_intent, context) {
         const squarePath = requireSquarePath(context);
-        const square = await openSquare(squarePath, { clock: nowMs });
-        try {
-            const presentation = await statusPresentation(square);
+        const application = createSquareApplication({ cwd: context.cwd, env: context.env, squarePath, clock: nowMs });
+        {
+            const presentation = await application.status();
             const result = presentation.status;
             const active = result.participants.filter((participant) => participant.state === 'active');
-            const people = active.length === 0 ? ['  ○ nobody in the square'] : active.slice(0, STATUS_PARTICIPANT_PREVIEW_LIMIT).map((participant) => {
-                const glyph = participant.presence === 'watching'
-                    ? '◎'
-                    : participant.activityCount > 0 ? '●' : '○';
-                const summary = participant.activityCount > 0
-                    ? `${participant.activityCount} ${participant.activityCount === 1 ? 'activity' : 'activities'} · ${participant.lastActiveAt === undefined
-                        ? 'just now'
-                        : formatRelativeTime(participant.lastActiveAt, result.now)}`
-                    : `quiet · ${participant.lastActiveAt === undefined ? '—' : formatRelativeTime(participant.lastActiveAt, result.now)}`;
-                const showAttention = context.name === undefined || sameName(participant.name, context.name);
-                const attention = !showAttention
-                    ? ''
-                    : participant.pendingMentionCount > 0
-                        ? `${participant.pendingMentionCount} attention${participant.pendingMentionCount === 1 ? '' : 's'} waiting`
-                        : participant.unreadActivityCount > 0
-                            ? `${participant.unreadActivityCount} change${participant.unreadActivityCount === 1 ? '' : 's'} waiting`
-                            : 'caught up';
-                return `  ${glyph} ${participantIdentity(participant.name)} · ${summary}${attention === '' ? '' : ` · ${attention}`}`;
-            });
-            if (active.length > STATUS_PARTICIPANT_PREVIEW_LIMIT) {
-                people.push(`  ○ … ${active.length - STATUS_PARTICIPANT_PREVIEW_LIMIT} more participants`);
-                people.push(`» ${result.participants.length <= PARTICIPANTS_MAX_LIMIT
-                    ? participantsLimitCommand(squarePath, result.participants.length)
-                    : `${commandPrefix(squarePath)} participants`}`);
+            const here = active.filter((participant) => participant.presence === 'watching'
+                || (participant.lastActiveAt !== undefined && result.now - participant.lastActiveAt <= STATUS_HERE_WINDOW_MS));
+            const lingering = active.length - here.length;
+            const orderedHere = [
+                ...here.filter((participant) => participant.presence === 'watching'),
+                ...here.filter((participant) => participant.presence !== 'watching'),
+            ];
+            const people = [];
+            if (active.length === 0) {
+                people.push('  ○ nobody in the square');
+            }
+            else {
+                if (orderedHere.length === 0)
+                    people.push('  ○ nobody here right now');
+                people.push(...orderedHere.slice(0, STATUS_PARTICIPANT_PREVIEW_LIMIT).map((participant) => {
+                    const glyph = participant.presence === 'watching'
+                        ? '◎'
+                        : participant.activityCount > 0 ? '●' : '○';
+                    const summary = participant.presence === 'watching'
+                        ? 'catching'
+                        : participant.activityCount > 0
+                            ? formatRelativeTime(participant.lastActiveAt ?? result.now, result.now)
+                            : `quiet · ${participant.lastActiveAt === undefined ? 'just now' : formatRelativeTime(participant.lastActiveAt, result.now)}`;
+                    const showAttention = context.name === undefined || sameName(participant.name, context.name);
+                    const attention = !showAttention
+                        ? ''
+                        : participant.pendingMentionCount > 0
+                            ? `${participant.pendingMentionCount} ${participant.pendingMentionCount === 1 ? 'mention' : 'mentions'} waiting`
+                            : participant.unreadActivityCount > 0
+                                ? `${participant.unreadActivityCount} change${participant.unreadActivityCount === 1 ? '' : 's'} waiting`
+                                : 'caught up';
+                    return `  ${glyph} ${participantIdentity(participant.name)}${style('dim', ` · ${summary}${attention === '' ? '' : ` · ${attention}`}`)}`;
+                }));
+                const unshown = Math.max(0, orderedHere.length - STATUS_PARTICIPANT_PREVIEW_LIMIT) + lingering;
+                if (orderedHere.length > STATUS_PARTICIPANT_PREVIEW_LIMIT) {
+                    people.push(`  ○ … ${orderedHere.length - STATUS_PARTICIPANT_PREVIEW_LIMIT} more here`);
+                }
+                if (lingering > 0)
+                    people.push(`  ○ … ${lingering} lingering`);
+                if (unshown > 0) {
+                    people.push(`${result.participants.length <= PARTICIPANTS_MAX_LIMIT
+                        ? participantsLimitCommand(squarePath, result.participants.length)
+                        : `${commandPrefix(squarePath)} participants`}`);
+                }
             }
-            const cap = result.hardCap === null ? 'unlimited' : String(result.hardCap);
+            const cap = result.hardCap === null ? 'unlimited' : `${result.hardCap} each`;
+            const holdTime = result.holdAt === undefined ? 'just now' : formatRelativeTime(result.holdAt, result.now);
             const hold = result.holdActive
-                ? `· ${result.holdActor === undefined ? 'someone' : participantIdentity(result.holdActor)} raised a hand${result.holdReason ? ` — ${result.holdReason}` : ''} · ${result.holdAt === undefined
-                    ? 'just now'
-                    : formatRelativeTime(result.holdAt, result.now)}`
+                ? `· ${result.holdActor === undefined ? 'someone' : participantIdentity(result.holdActor)} raised a hand${result.holdReason ? ` — ${result.holdReason}` : ''}${style('dim', ` · ${holdTime}`)}`
                 : undefined;
             const visible = result.latestAct === undefined
                 ? ''
@@ -510,20 +564,34 @@ export const statusCommand = {
             const latest = visible === ''
                 ? [result.latestAct === undefined
                         ? '  ○ no public activity yet'
-                        : '  · latest activity is private to another participant']
+                        : '  · the latest words were meant for other ears']
                 : [`  ${visible.replace(/\n/g, '\n  ')}`];
+            // Presence events after the latest public act: otherwise the roster can say someone is
+            // here while the latest line shows them leaving, with nothing to reconcile the two.
+            const latestIndex = result.latestAct?.index ?? -1;
+            const stepsIn = presentation.state.acts.filter((act) => act.kind === 'join' && act.index > latestIndex);
+            for (const act of stepsIn.slice(-3)) {
+                const rejoined = presentation.state.acts.some((other) => other.kind === 'done' && other.actor === act.actor && other.index < act.index);
+                latest.push(style('dim', `  → ${participantIdentity(act.actor)} ${rejoined ? 'stepped back in' : 'stepped in'} · ${formatRelativeTime(act.at, result.now)}`));
+            }
+            if (stepsIn.length > 3)
+                latest.push(style('dim', `  → … ${stepsIn.length - 3} more stepped in`));
             if (visible.includes('more chars') && result.latestAct !== undefined) {
-                latest.push(`» ${commandPrefix(squarePath)} history --at ${actId(result.latestAct)} -C 2 --no-truncate`);
+                latest.push(`${commandPrefix(squarePath)} history --at ${actId(result.latestAct)} -C 2 --no-truncate`);
             }
+            const counts = [
+                `${here.length} here`,
+                ...(lingering > 0 ? [`${lingering} lingering`] : []),
+                `${result.doneCount} done`,
+                `cap ${cap}`,
+                `throttle ${result.throttlePerMinute === undefined ? 'none' : `${result.throttlePerMinute}/min`}`,
+            ].join(' · ');
             const output = [
-                `${result.activeCount} active · ${result.doneCount} done · cap ${cap} · throttle ${result.throttlePerMinute === undefined ? 'none' : `${result.throttlePerMinute}/min`}`,
-                ...(hold === undefined ? [] : ['', hold]), '', 'around the square', ...people, '', 'latest', ...latest,
+                style('dim', counts),
+                ...(hold === undefined ? [] : ['', hold]), '', style('dim', 'around the square'), ...people, '', style('dim', 'latest'), ...latest,
             ].join('\n');
             return withPathOutput(squarePath, output, { participantCount: result.activeCount, held: result.holdActive });
         }
-        finally {
-            await closeOpenSquare(square);
-        }
     },
     present: (result) => process.stdout.write(result),
 };
@@ -558,7 +626,7 @@ export const inboxCommand = {
             fail('inbox requires --for-session <session-id>.');
         const retry = inboxLimitCommand(sessionId, json);
         if (duplicateLimit)
-            fail(`✕ inbox accepts one --limit\n» ${retry}`);
+            fail(`✕ inbox accepts one --limit\n${retry}`);
         const limit = hasLimit
             ? parseBoundedLimit(limitValue, '--limit', INBOX_MAX_LIMIT, retry)
             : INBOX_DEFAULT_LIMIT;

package/dist/cli/program.js

@@ -1,20 +1,47 @@
 import { helpRequest } from '../help.js';
 import { isSquareError } from '../model.js';
-import { joinRecoveryCommand, participantsRecoveryCommand } from '../presentation.js';
+import { formatRefusal, joinRecoveryCommand, participantsRecoveryCommand, takeoverRecoveryLines } from '../presentation.js';
+import { inSquareCount, nowMs } from '../runtime.js';
+import { openSquare } from '../square-file-adapter.js';
+import { closeOpenSquare } from '../open-square.js';
 import { defaultContext, parseGlobalArgs } from './context.js';
 import { executeRegisteredCommand, findCommand } from './registry.js';
-function handleSquareError(error, squarePath, name) {
+async function participantCountFor(squarePath) {
+    try {
+        const square = await openSquare(squarePath, { clock: nowMs });
+        try {
+            return inSquareCount((await square.artifact.read()).state);
+        }
+        finally {
+            await closeOpenSquare(square);
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+async function handleSquareError(error, squarePath, name) {
     if (isSquareError(error)) {
-        process.stderr.write(`${error.message}\n`);
-        if (squarePath !== undefined && /^Unknown participant/.test(error.message)) {
+        const existing = [error.message];
+        if (squarePath !== undefined && name !== undefined && error.code === 'already_joined') {
+            existing.push(...takeoverRecoveryLines(squarePath, name));
+        }
+        else if (squarePath !== undefined && /^✕ .* has never stepped into/.test(error.message)) {
             // The caller's name has never joined this square; only a join admits it.
             if (name !== undefined)
-                process.stderr.write(`${joinRecoveryCommand(squarePath, name)}\n`);
+                existing.push(joinRecoveryCommand(squarePath, name));
             else
-                process.stderr.write(`${participantsRecoveryCommand(squarePath)}\n`);
+                existing.push(participantsRecoveryCommand(squarePath));
+        }
+        else if (squarePath !== undefined && /^✕ .* is not standing in this square/.test(error.message)) {
+            existing.push(participantsRecoveryCommand(squarePath));
+        }
+        if (squarePath === undefined) {
+            process.stderr.write(`${existing.join('\n')}\n`);
         }
-        else if (squarePath !== undefined && /^Unknown mention target/.test(error.message)) {
-            process.stderr.write(`${participantsRecoveryCommand(squarePath)}\n`);
+        else {
+            const participantCount = await participantCountFor(squarePath);
+            process.stderr.write(formatRefusal(squarePath, existing, participantCount === undefined ? {} : { participantCount }));
         }
         process.exit(error.code === 'not_found' ? 1 : 2);
     }
@@ -45,6 +72,6 @@ export async function runCli(rawArgs = process.argv.slice(2)) {
         await executeRegisteredCommand(command, parsed.args.slice(1), defaultContext(command, parsed.squarePath, parsed.name));
     }
     catch (error) {
-        handleSquareError(error, squarePath, requestedName);
+        await handleSquareError(error, squarePath, requestedName);
     }
 }

package/dist/cli/registry.js

@@ -2,6 +2,7 @@ import { buildCommand, doneCommand, expressCommand, holdCommand, ignoreCommand,
 import { doctorCommand } from './maintenance-commands.js';
 import { harnessCommand, installCommand, uninstallCommand } from './harness-command.js';
 import { helpCommand, versionCommand } from './meta-commands.js';
+import { mcpServerCommand } from './mcp-server-command.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 = [
@@ -29,6 +30,7 @@ export const commandRegistry = [
     { names: ['participants'], spec: participantsCommand },
     { names: ['help'], spec: helpCommand },
     { names: ['version', '--version', '-v'], spec: versionCommand },
+    { names: ['mcp-server'], spec: mcpServerCommand },
 ];
 export function findCommand(name) {
     return commandRegistry.find((command) => command.names.includes(name));

package/dist/cli/square-commands.d.ts

@@ -19,7 +19,7 @@ interface ActivityIntent {
     noMention: boolean;
     mentions: string[];
     reach?: Reach;
-    reply?: number;
+    reply?: string;
 }
 interface BodyIntent {
     name: string;