@astrosheep/square 0.3.77 → 0.3.79

package/dist/cli/program.js

@@ -1,18 +1,24 @@
 import { helpRequest } from '../help.js';
 import { isSquareError } from '../model.js';
 import { commandPrefix, formatRefusal, refusalText, joinRecoveryCommand, participantIdentity, participantsRecoveryCommand, takeoverRecoveryLines, } from '../presentation.js';
-import { applicationFor, defaultContext, parseGlobalArgs } from './context.js';
+import { withSquare, defaultContext, parseGlobalArgs } from './context.js';
 import { executeRegisteredCommand, findCommand } from './registry.js';
 async function handleSquareError(error, context) {
     if (!isSquareError(error))
         throw error;
     const detail = error.operation;
     const squarePath = context?.squarePath;
-    const recovery = context === undefined || squarePath === undefined ? undefined
-        : await applicationFor({ ...context, name: detail?.participant ?? context.name }).recovery().catch(() => undefined);
-    const name = detail?.participant ?? recovery?.data.participant ?? context?.name;
+    const recovery = error.facts?.reason === 'migration_required' || context === undefined || squarePath === undefined ? undefined
+        : await withSquare({ ...context, name: detail?.participant ?? context.name }, (square) => square.recovery(detail?.participant ?? context.name)).catch(() => undefined);
+    const name = detail?.participant ?? recovery?.participant ?? context?.name;
     const existing = [refusalText(error)];
-    if (squarePath !== undefined && name !== undefined && error.code === 'already_joined') {
+    if (error.facts?.reason === 'migration_required') {
+        if (error.facts.ledgerRoot !== undefined)
+            existing.push('square ledger migrate', 'square ledger verify');
+        else if (squarePath !== undefined)
+            existing.push(`${commandPrefix(squarePath)} migrate`);
+    }
+    else if (squarePath !== undefined && name !== undefined && error.code === 'already_joined') {
         existing.splice(0, 1, `✕ ${participantIdentity(name)} shoos you out of the square`, `  · ${participantIdentity(name)} already stands here — another session holds the name`);
         existing.push(...takeoverRecoveryLines(squarePath, name));
     }
@@ -34,11 +40,11 @@ async function handleSquareError(error, context) {
         process.stderr.write(`${existing.join('\n')}\n`);
     else
         process.stderr.write(formatRefusal(squarePath, existing, {
-            participantCount: recovery?.data.standingCount, held: recovery?.data.held,
+            participantCount: recovery?.standingCount, held: recovery?.held,
         }));
     process.exit(error.code === 'not_found' ? 1 : 2);
 }
-/** Parse global flags, select an executable adapter, and leave operations to the application. */
+/** Parse global flags, select an adapter, and execute through Square/Participant. */
 export async function runCli(rawArgs = process.argv.slice(2)) {
     let context;
     try {

package/dist/cli/square-commands.js

@@ -1,9 +1,9 @@
 import { formatHardCap } from '../model.js';
 import { commandPrefix, participantCommandPrefix, participantIdentity, renderRoomChangeText, renderAmbientEvent, withPathOutput, } from '../presentation.js';
-import { formatActivityId } from '../square-application.js';
+import { Square, formatActivityId } from '../square-api.js';
 import { style } from '../tty-style.js';
 import { executeExpression } from './express-presentation.js';
-import { applicationFor, fail, parseBoundedLimit, parseHardCap, parsePositiveInteger, readStdin, requireSquarePath, requireValue, resolveBody, usage, } from './context.js';
+import { squareInput, withSquare, fail, parseBoundedLimit, parseHardCap, parsePositiveInteger, readStdin, requireSquarePath, requireValue, resolveBody, usage, } from './context.js';
 const JOIN_DEFAULT_LAST = 10;
 const JOIN_MAX_LAST = 100;
 export const buildCommand = {
@@ -42,11 +42,18 @@ export const buildCommand = {
         const markdown = await readStdin();
         if (markdown.trim() === '')
             fail('Missing Markdown body snippet on stdin.');
-        const { data, projection } = await applicationFor(context).build({ ...intent.options, markdown });
+        const square = await Square.build({ ...squareInput(context), ...intent.options, markdown });
+        let data;
+        try {
+            data = await square.status();
+        }
+        finally {
+            await square.close();
+        }
         const cap = data.hardCap === null ? 'unlimited' : formatHardCap(data.hardCap);
         const throttle = data.throttlePerMinute === undefined ? [] : [`  · throttle ${data.throttlePerMinute}/min`];
-        return withPathOutput(data.location, ['· the square stands ready', `  · cap ${cap}`, ...throttle].join('\n'), {
-            participantCount: projection.standingCount, held: projection.held,
+        return withPathOutput(square.location, ['· the square stands ready', `  · cap ${cap}`, ...throttle].join('\n'), {
+            participantCount: 0, held: false,
         });
     },
     present: (result) => process.stdout.write(result),
@@ -68,12 +75,14 @@ export const joinCommand = {
         return { lastN, kick };
     },
     async execute(intent, context) {
-        const { data, projection: after } = await applicationFor(context).join({ takeover: intent.kick, last: intent.lastN });
-        const name = data.participant;
-        const activities = after.recentActivities.map((event) => renderAmbientEvent(event, name, {
+        const data = await withSquare(context, (square) => square.join(context.name, { takeover: intent.kick, last: intent.lastN, observe: true }));
+        const after = data.observation;
+        const entry = after.entry;
+        const name = data.participant.name;
+        const activities = (entry?.recentActivities ?? []).map((event) => renderAmbientEvent(event, name, {
             now: after.now, preview: 200,
-            actNumber: event.kind === 'say' ? after.sayNumbers[event.index] : undefined,
-            perception: after.perceptions[event.index],
+            actNumber: event.kind === 'say' ? entry.sayNumbers[event.index] : undefined,
+            perception: entry.perceptions[event.index],
         })).filter(Boolean).join('\n\n');
         const fallback = after.automaticDeliveryAvailable ? [] : [
             '', `${participantCommandPrefix(after.location, name)} catch --idle 30m`,
@@ -83,13 +92,14 @@ export const joinCommand = {
             : data.kind === 'reconnected' ? '● you are already in the square'
                 : `✓ you banished the original ${participantIdentity(name)} — the name is yours`;
         const isRejoin = data.kind !== 'joined';
-        const entryScene = isRejoin ? '' : after.joinedBefore
-            ? '*the flagstones are where you left them. so is your shadow.*' : after.scene;
+        const entryScene = isRejoin || entry === undefined ? '' : entry.joinedBefore
+            ? '*the flagstones are where you left them. so is your shadow.*' : entry.scene;
         return withPathOutput(after.location, [
             entryLine, '',
             "· carved into the fountain's edge: every word here lands on a real ear — speak when someone needs it.",
             ...(entryScene === '' ? [] : ['', entryScene]),
-            ...(isRejoin || after.joinContext === '' ? [] : ['', style('dim', 'context'), after.joinContext]),
+            ...(isRejoin || !entry?.joinContext ? [] : ['', style('dim', 'context'), entry.joinContext]),
+            ...(after.enrichmentUnavailable ? ['  · joined; recent activity and context are unavailable right now'] : []),
             ...(isRejoin || activities === '' ? [] : ['', style('dim', 'recent activity'), activities]),
             ...fallback,
         ].join('\n'), { participantCount: after.standingCount, held: after.held });
@@ -128,10 +138,6 @@ function parseActivity(argv, context) {
             bodyArgs.push(argument);
     }
     const reach = bell ? 'bell' : undefined;
-    if (bell && (noMention || mentions.length > 0))
-        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\nsquare express --help');
     if (bodyArgs.length !== 1) {
         if (bodyArgs.length === 0 && !process.stdin.isTTY)
             bodyArgs.push('-');
@@ -144,7 +150,7 @@ export const expressCommand = {
     parse: parseActivity,
     async execute(intent, context) {
         const rawInput = await resolveBody(intent.activity);
-        await executeExpression(applicationFor(context), requireSquarePath(context), context.name, rawInput, {
+        await executeExpression((control) => Square.at(squareInput(context), control), requireSquarePath(context), context.name, rawInput, {
             force: intent.force, noWait: intent.noWait, noMention: intent.noMention,
             mentions: intent.mentions, reach: intent.reach, reply: intent.reply,
         });
@@ -160,7 +166,8 @@ function listenerCommand(verb) {
     return {
         parse(argv, context) { return parseListener(argv, context, true); },
         async execute(intent, context) {
-            const { data, projection } = await applicationFor(context)[verb](intent.target);
+            const data = await withSquare(context, async (square) => (await square.participant(context.name))[verb](intent.target, { observe: true }));
+            const projection = data.observation;
             const actor = participantIdentity(projection.participant);
             const target = participantIdentity(projection.target);
             const action = data.activity !== null
@@ -178,7 +185,8 @@ export const ignoreCommand = listenerCommand('ignore');
 export const listeningCommand = {
     parse(argv, context) { return parseListener(argv, context, false); },
     async execute(_intent, context) {
-        const { data, projection } = await applicationFor(context).listening();
+        const data = await withSquare(context, async (square) => (await square.participant(context.name)).listening({ observe: true }));
+        const projection = data.observation;
         const body = data.listening.length === 0
             ? `○ ${participantIdentity(projection.participant)} is not turned toward anyone`
             : ['listening', ...data.listening.map((target) => `  · ${participantIdentity(target)}`)].join('\n');
@@ -195,7 +203,8 @@ export const doneCommand = {
     async execute(intent, context) {
         const body = intent.body === '-' || ((intent.body === undefined || intent.body === '') && !process.stdin.isTTY)
             ? await readStdin() : intent.body;
-        const { data, projection } = await applicationFor(context).done(body);
+        const data = await withSquare(context, async (square) => (await square.participant(context.name)).done(body, { observe: true }));
+        const projection = data.observation;
         return withPathOutput(projection.location, `○ you stepped out — your footsteps fade · ${data.activity.id}`, {
             participantCount: projection.standingCount, held: projection.held,
         });
@@ -209,7 +218,9 @@ export const holdCommand = {
         return { body: argv[0] };
     },
     async execute(intent, context) {
-        const { projection } = await applicationFor(context).hold((await resolveBody(intent.body ?? '')).replace(/\r\n/g, '\n').trim());
+        const body = (await resolveBody(intent.body ?? '')).replace(/\r\n/g, '\n').trim();
+        const result = await withSquare(context, async (square) => (await square.participant(context.name)).hold(body, { observe: true }));
+        const projection = result.observation;
         return withPathOutput(projection.location, `· ${renderRoomChangeText(projection.activity)} · ${formatActivityId(projection.activity.index)} · just now`, { participantCount: projection.standingCount, held: projection.held });
     },
     present: (result) => process.stdout.write(result),
@@ -221,7 +232,8 @@ export const resumeCommand = {
         return {};
     },
     async execute(_intent, context) {
-        const { projection } = await applicationFor(context).resume();
+        const result = await withSquare(context, async (square) => (await square.participant(context.name)).resume({ observe: true }));
+        const projection = result.observation;
         return withPathOutput(projection.location, `✓ ${renderRoomChangeText(projection.activity)} · ${formatActivityId(projection.activity.index)} · just now`, { participantCount: projection.standingCount, held: projection.held });
     },
     present: (result) => process.stdout.write(result),

package/dist/decisions.d.ts

@@ -5,7 +5,7 @@ type TimedAct<K extends Act['kind'] = Act['kind']> = Extract<Act, {
 }> & {
     at: number;
 };
-import type { ParticipantSummary as ParticipantStatus, UnreadActivitySummary } from './square-facade.js';
+import type { ExpressOptions, ExpressResult, ParticipantSummary as ParticipantStatus, UnreadActivitySummary } from './square-facade.js';
 export type { ParticipantSummary as ParticipantStatus, ParticipantPresence as CorePresenceState, UnreadActivitySummary, UnreadActivityPreview } from './square-facade.js';
 export declare function resolveKnownName(facts: SquareRead, name: string): string;
 export interface DecideJoinResult {
@@ -20,11 +20,10 @@ export interface DecideImplicitJoinResult {
 }
 export declare function decideJoin(facts: SquareRead, name: string, now: number): DecideJoinResult;
 export declare function decideImplicitJoin(facts: SquareRead, name: string, now: number): DecideImplicitJoinResult;
-export type ActDecision = {
+export type ActDecision = ({
     type: 'sent';
     act: TimedAct;
-    replyAuthorNotHere?: string;
-} | {
+} & Pick<ExpressResult, 'replyAuthorNotHere' | 'unmatchedMentions'>) | {
     type: 'blocked';
     activitySummaries: UnreadActivitySummary[];
 } | {
@@ -43,6 +42,12 @@ export type ActDecision = {
 };
 /** Count the directed suffix, but hydrate only its last three previews per spelling. */
 export declare function unreadActivitySummaries(facts: SquareRead, name: string, now: number): UnreadActivitySummary[];
+export declare function expressionReach(input: {
+    body: string;
+} & Pick<ExpressOptions, 'reach' | 'mentions' | 'noMention'>): {
+    bodyMentions: string[];
+    hasReachWithoutReply: boolean;
+};
 export declare function decideAct(facts: SquareRead, input: {
     name: string;
     body: string;

package/dist/decisions.js

@@ -2,7 +2,7 @@ import { SquareError, isSquareError, sameName, nameKey, validateName, } from './
 import { participantIdentity } from './participant-identity.js';
 import { UNREAD_BLOCK_GRACE_MS, freshWatchLease, readCursor, FACT_PAGE_SIZE, THROTTLE_WINDOW_MS } from './runtime.js';
 import { formatActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
-import { scanMentionCandidates, resolveNameAt } from './mention-parse.js';
+import { scanMentionCandidates, resolveMention } from './mention-parse.js';
 export function resolveKnownName(facts, name) {
     validateName(name);
     const known = facts.participant(name)?.name;
@@ -84,6 +84,11 @@ export function unreadActivitySummaries(facts, name, now) {
         previews: summary.previews.map((preview) => ({ number: preview.number, act: byIndex.get(preview.index), perception: 'full' })),
     })).sort((a, b) => a.latestActivityAgeMs - b.latestActivityAgeMs || a.name.localeCompare(b.name));
 }
+export function expressionReach(input) {
+    const bodyMentions = input.reach === 'bell' || input.noMention === true ? [] : scanMentionCandidates(input.body);
+    const hasReachWithoutReply = input.reach === 'bell' || (input.mentions?.length ?? 0) > 0 || input.noMention === true || bodyMentions.length > 0;
+    return { bodyMentions, hasReachWithoutReply };
+}
 export function decideAct(facts, input) {
     const { now, force, body, reach, reply } = input;
     const current = resolveStanding(facts, input.name, true);
@@ -92,6 +97,8 @@ export function decideAct(facts, input) {
         throw activityRefusal('invalid_args', 'express body cannot be empty');
     const roster = facts.roster();
     const joinedNames = roster.filter((participant) => participant.joined).map((participant) => participant.name);
+    if (reach === 'bell' && input.mentions?.length)
+        throw activityRefusal('invalid_args', 'A bell cannot be combined with a mention', { reason: 'bell_mention_conflict', targets: [...input.mentions] });
     const mentionNames = [];
     const addMention = (resolved) => {
         if (mentionNames.some((existing) => sameName(existing, resolved)))
@@ -107,21 +114,22 @@ export function decideAct(facts, input) {
             throw activityRefusal('invalid_args', `${participantIdentity(requested)} is not standing in this square`, { reason: 'not_standing', targets: [requested] });
         addMention(resolved);
     }
-    const bodyMentions = input.noMention === true ? [] : scanMentionCandidates(body);
-    for (const candidate of bodyMentions) {
-        const resolved = resolveNameAt(body, candidate, joinedNames);
+    const { bodyMentions, hasReachWithoutReply } = expressionReach(input);
+    const unmatchedMentions = [];
+    for (const token of bodyMentions) {
+        const resolved = resolveMention(token, joinedNames);
         if (resolved !== undefined)
             addMention(resolved);
+        else
+            unmatchedMentions.push(token);
     }
-    if (reach === 'bell' && mentionNames.length > 0)
-        throw activityRefusal('invalid_args', 'A bell cannot be combined with a mention', { reason: 'bell_mention_conflict', targets: mentionNames });
-    if (input.requireExplicitReach && reach !== 'bell' && mentionNames.length === 0 && bodyMentions.length === 0 && reply === undefined && input.noMention !== true) {
+    if (input.requireExplicitReach && !hasReachWithoutReply && reply === undefined) {
         throw activityRefusal('invalid_args', 'Express needs a recipient, reply, bell, or explicit bare reach', { reason: 'explicit_reach_required' });
     }
     const header = facts.header();
     if (reply !== undefined && (!Number.isSafeInteger(reply) || reply < 0 || reply >= header.nextActIndex)) {
         const label = Number.isSafeInteger(reply) && reply >= 0 ? formatActivityId(reply) : String(reply);
-        throw activityRefusal('invalid_args', `Unknown reply activity: ${label}`, { reason: 'invalid_reply', activityId: label, activityExists: false });
+        throw activityRefusal('invalid_args', `Unknown reply activity: ${label}`, { reason: 'invalid_reply', activityId: label, activityExists: false, hasReachWithoutReply });
     }
     const replyAuthor = reply === undefined ? undefined : facts.activity(reply)?.actor;
     const replyAuthorNotHere = replyAuthor === undefined || sameName(replyAuthor, name) || facts.participant(replyAuthor)?.joined ? undefined : replyAuthor;
@@ -152,6 +160,7 @@ export function decideAct(facts, input) {
     }
     return { type: 'sent', act: { kind: 'say', actor: name, at: now, body, mentions: mentionNames,
             ...(reach === undefined ? {} : { reach }), ...(reply === undefined ? {} : { reply }) },
+        ...(unmatchedMentions.length === 0 ? {} : { unmatchedMentions }),
         ...(replyAuthorNotHere === undefined ? {} : { replyAuthorNotHere }) };
 }
 export function validateDoneBody(body) {

package/dist/delivery.d.ts

@@ -47,7 +47,7 @@ export declare function pendingPages(artifact: SquareArtifactPort, scan: Pending
     at: number;
     actor: string;
     recipient: string;
-    route: "bell" | "mention" | "reply" | "attention";
+    route: "bell" | "reply" | "mention" | "attention";
 }[], void, unknown>;
 /** A pass retains only its captured joins; routes and individual receipts are fresh. */
 export declare function pendingFacts(facts: SquareRead, scan: PendingScan, heads: readonly DirectedHead[]): {

package/dist/help.js

@@ -17,9 +17,22 @@ const COMMANDS = [
         details: ['Options:', '  --last <N>  Show the last N public activities (default 10, maximum 100).', '  --kick      End the standing participant and reclaim the name for this session.'],
     },
     {
-        names: ['express'], usage: '--as <name> express [-f|--force] [--no-wait] (--mention <name>... | --no-mention | --bell | --reply <activity-id>) <activity | ->', usesSquare: true, group: 'participant',
+        names: ['express'], usage: '--as <name> express [-f|--force] [--no-wait] [--mention <name>... | --bell] [--no-mention] [--reply <activity-id>] <activity | ->', usesSquare: true, group: 'participant',
         summary: 'Speak, gesture, or do both.',
-        details: ['Reach:', '  --mention <name>  Address one participant; repeat for multiple participants. The body stays unchanged.', '  --no-mention      Land a bare activity explicitly; @names stay plain text. listen opts someone into future bare delivery.', "  --bell            Call every participant's attention to this activity.", '  @name             An @name in the body also addresses that standing participant; `backticks` keep @text literal.', '', 'Options:', '  -f, --force       Express without first catching unread activity or attention etiquette.', '  --no-wait         If held or throttled, save a draft and return instead of waiting. A held wait gives up on its own after 10 minutes.', '  --reply <activity-id>   Mark this activity as a reply to an earlier activity (for example act/12); it reaches that activity\'s author.'],
+        details: [
+            'Reach:',
+            '  --mention <name>  Address one standing participant; repeat to address more.',
+            '  @name             Also address a standing participant named in the body; `backticks` keep @text literal.',
+            "  --bell            Call everyone; body @names stay literal. Cannot combine with --mention.",
+            '  --no-mention      Keep body @names literal; explicit --mention and --reply still apply.',
+            '  --reply <activity-id>   Also reach the author of an earlier activity (for example act/12).',
+            '  Choose reach with a flag above or an @name in the body. Unmatched @names stay literal, with a notice.',
+            '  With no mention, bell, or reply, the activity lands bare; only listeners receive it.',
+            '',
+            'Options:',
+            '  -f, --force       Express without first catching unread activity or satisfying attention etiquette.',
+            '  --no-wait         If held or throttled, save a draft and return instead of waiting. A held wait gives up on its own after 10 minutes.',
+        ],
     },
     { names: ['listen'], usage: '--as <name> listen <participant>', usesSquare: true, group: 'participant', summary: 'Turn an ear toward one participant\'s future bare says.' },
     { names: ['ignore'], usage: '--as <name> ignore <participant>', usesSquare: true, group: 'participant', summary: 'Ignore one participant\'s future mentions and bare says.' },

package/dist/host-ledger-migration.js

@@ -5,7 +5,7 @@ import { DatabaseSync } from 'node:sqlite';
 import { canonicalPathSync } from './canonical-path.js';
 import { withFileLock } from './file-lock.js';
 import { hostLedgerRoot } from './host-ledger-root.js';
-import { LEDGER_FILENAME, initializeLedger, insertLedgerRecord, ledgerRecordColumns, setLedgerRevisions, upgradeLedger, validateLedger, verifyLedger, inspectLedgerIdentity, } from './host-ledger-sqlite.js';
+import { LEDGER_FILENAME, initializeLedger, insertLedgerRecord, ledgerRecordColumns, setLedgerRevisions, upgradeLedger, validateLedger, verifyLedger, inspectLedgerIdentity, migrationRequired, } from './host-ledger-sqlite.js';
 import { inSqliteTransaction } from './sqlite-transaction.js';
 function rootFor(options) {
     return canonicalPathSync(options.rootPath ?? hostLedgerRoot(options.env));
@@ -25,10 +25,6 @@ async function exists(file) {
         throw error;
     }
 }
-function migrationGuidance(root, file) {
-    const name = file ?? path.join(root, LEDGER_FILENAME);
-    return `Host ledger at ${root} has a supported older format (${name}).\nStop agent sessions and MCP services using Square with this ledger; keep them stopped until migration and verification succeed; then start them with the updated Square version.\nsquare ledger migrate\nsquare ledger verify`;
-}
 function verificationFailure(root, file, format) {
     const name = file ?? path.join(root, LEDGER_FILENAME);
     const detail = format === 'unsupported'
@@ -62,7 +58,7 @@ async function verifyDatabase(file, root, signal) {
             db = undefined;
         }
         if (format === 'old-sqlite')
-            throw new Error(migrationGuidance(root, file));
+            throw migrationRequired(root);
         throw verificationFailure(root, file, format);
     }
     finally {

package/dist/host-ledger-sqlite.js

@@ -3,7 +3,7 @@ import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { nameKey } from './model.js';
+import { SquareError, nameKey } from './model.js';
 import { inSqliteTransaction, retrySqliteBusy } from './sqlite-transaction.js';
 export const LEDGER_FILENAME = 'host-ledger.sqlite';
 export const LEDGER_APPLICATION_ID = 0x5351484c;
@@ -175,7 +175,7 @@ catch (error) {
     throw error;
 } }
 export function migrationRequired(root) {
-    return new Error(`Host ledger legacy format needs offline migration at ${root}.\nStop agent sessions and MCP services using Square with this ledger; keep them stopped until migration and verification succeed; then start them with the updated Square version.\nRun square ledger migrate from the same environment, then square ledger verify.`);
+    return new SquareError('invalid_args', `Host ledger at ${root} needs offline migration.\nStop sessions and MCP services using it, back it up, then migrate and verify from the same environment before restarting.`, { reason: 'migration_required', ledgerRoot: root });
 }
 /** Compact runtime framing. Full schema, projections and integrity belong to explicit verify. */
 function validateLedgerHeader(db, version = LEDGER_VERSION) {

package/dist/inbox.js

@@ -5,7 +5,7 @@ import { canonicalPath } from './canonical-path.js';
 import { projectBoundaryEligibility, projectSessionBindings } from './square-projections.js';
 import { freshWatchLease, WATCH_STALE_MS } from './runtime.js';
 import { pendingHead, pendingNotifications, leaseOwnsNotification } from './delivery.js';
-import { attentionBodyIsClipped, renderAttentionPreview } from './attention-presentation.js';
+import { attentionBodyIsClipped, renderAttentionPreview, renderSquareReminder } from './attention-presentation.js';
 function bindingCoordinate(binding) {
     return JSON.stringify([binding.location, nameKey(binding.participant), binding.sessionId, binding.channel, binding.epoch, binding.cancelledThrough ?? -1]);
 }
@@ -37,8 +37,8 @@ export function nativePendingPreview(facts, input) {
     const item = facts.activity(input.actIndex);
     if (item?.kind !== 'say')
         return undefined;
-    return { payload: renderAttentionPreview({ squarePath: input.location, recipient: input.participant, actIndex: item.index,
-            actor: item.actor, route: head.route, body: item.body }), clipped: attentionBodyIsClipped(item.body) };
+    return { payload: renderSquareReminder([renderAttentionPreview({ squarePath: input.location, recipient: input.participant, actIndex: item.index,
+                actor: item.actor, route: head.route, body: item.body })]), clipped: attentionBodyIsClipped(item.body) };
 }
 async function readInboxMembership(binding, signal) {
     const artifact = createArtifactPort(binding.location, undefined, signal);

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-export { Square } from './square-application.js';
-export { createSquareApplication } from './square-application.js';
+export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare, migrateSquare } from './square-api.js';
 export { SquareError } from './model.js';
 export { squareAssignedParticipantName } from './registry.js';
 export { createDefaultWakeTransport } from './notifications.js';

package/dist/index.js

@@ -1,5 +1,4 @@
-export { Square } from './square-application.js';
-export { createSquareApplication } from './square-application.js';
+export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare, migrateSquare } from './square-api.js';
 export { SquareError } from './model.js';
 export { squareAssignedParticipantName } from './registry.js';
 export { createDefaultWakeTransport } from './notifications.js';

package/dist/ledger-maintenance.d.ts

@@ -22,7 +22,7 @@ export interface LedgerMaintenanceReport {
     /** Canonical locations whose artifact could not be read; their rows were retained. */
     readonly unavailableArtifacts: readonly string[];
 }
-/** Command/application entry: root selection uses the caller's captured environment. */
+/** Maintenance entry: root selection uses the caller's captured environment. */
 export declare function gcHostLedger(options?: LedgerMaintenanceOptions & {
     readonly env?: NodeJS.ProcessEnv;
 }): Promise<LedgerMaintenanceReport>;

package/dist/ledger-maintenance.js

@@ -62,7 +62,7 @@ async function provenClosable(location, group) {
         await artifact.close();
     }
 }
-/** Command/application entry: root selection uses the caller's captured environment. */
+/** Maintenance entry: root selection uses the caller's captured environment. */
 export function gcHostLedger(options = {}) {
     return maintainHostLedger(hostLedgerForEnv(options.env ?? process.env), options);
 }

package/dist/list.d.ts

@@ -1,7 +1,7 @@
-import type { DiscoveryApplicationData, DiscoveryApplicationOptions, OpenOptions, OperationControl } from './square-facade.js';
+import type { DiscoveryResult, DiscoveryOptions, OpenOptions, OperationControl } from './square-facade.js';
 export declare const DEFAULT_LIST_DEPTH = 4;
 export declare const MAX_LIST_DEPTH = 16;
 export declare const DEFAULT_LIST_LIMIT = 20;
 export declare const MAX_LIST_LIMIT = 100;
-/** Bounded deterministic discovery. Only the application calls this private operation. */
-export declare function discoverSquares(root: string, options?: DiscoveryApplicationOptions, control?: OperationControl, openOptions?: OpenOptions): Promise<DiscoveryApplicationData>;
+/** Bounded deterministic discovery for the public resource API. */
+export declare function discoverSquares(root: string, options?: DiscoveryOptions, control?: OperationControl, openOptions?: OpenOptions): Promise<DiscoveryResult>;

package/dist/list.js

@@ -32,7 +32,7 @@ async function readSquareListItem(filePath, root, options, control) {
         return null;
     }
 }
-/** Bounded deterministic discovery. Only the application calls this private operation. */
+/** Bounded deterministic discovery for the public resource API. */
 export async function discoverSquares(root, options = {}, control, openOptions = {}) {
     const depth = options.depth ?? DEFAULT_LIST_DEPTH;
     const limit = options.limit ?? DEFAULT_LIST_LIMIT;

package/dist/mcp.d.ts

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { SquareApplicationContext } from './square-facade.js';
+import type { SquareAtInput } from './square-facade.js';
 /** The server owns its artifact connection lifetime, so callers cannot lend one. */
-export interface SquareMcpOptions extends Omit<SquareApplicationContext, 'resources'> {
+export interface SquareMcpOptions extends Omit<SquareAtInput, 'resources'> {
 }
 export type SquareMcpServer = McpServer;
 export declare function createSquareMcpServer(options: SquareMcpOptions): SquareMcpServer;

package/dist/mcp.js

@@ -4,9 +4,9 @@ import { SQUARE_TOOLS, SQUARE_TOOL_INSTRUCTIONS, squareToolFailure } from './squ
 import { operationEnv } from './automatic-session.js';
 import { readClaudeMcpCall } from './claude-mcp-context.js';
 import { SQUARE_IDENTITY } from './identity.js';
-import { createSquareApplication, createSquareResourceOwner } from './square-application.js';
+import { Square, createSquareResourceOwner } from './square-api.js';
 export function createSquareMcpServer(options) {
-    const baseEnv = { ...options.env };
+    const baseEnv = { ...(options.env ?? process.env) };
     const resources = createSquareResourceOwner();
     // Calls to the configured square borrow one server-owned connection.
     const inFlight = new Set();
@@ -33,15 +33,20 @@ export function createSquareMcpServer(options) {
                             : typeof opencodeSessionId === 'string' && opencodeSessionId.trim()
                                 ? operationEnv('opencode', opencodeSessionId, baseEnv)
                                 : baseEnv;
-                    const app = createSquareApplication({
+                    const square = await Square.at({
                         ...options, env, cwd: claude?.cwd ?? options.cwd,
-                        squarePath: location ?? options.squarePath,
+                        path: location ?? options.path,
                         participant: participant ?? options.participant,
                         // The server owner is bound to its configured square; overrides close after each call.
                         resources: location === undefined && claude === undefined ? resources : undefined,
-                    }, { presentation: false });
-                    const outcome = await tool.run(app, args, { signal: extra.signal });
-                    const structuredContent = outcome.data;
+                    }, { signal: extra.signal });
+                    let structuredContent;
+                    try {
+                        structuredContent = await tool.run(square, args, { signal: extra.signal });
+                    }
+                    finally {
+                        await square.close();
+                    }
                     return { content: [{ type: 'text', text: JSON.stringify(structuredContent) }], structuredContent };
                 }
                 catch (error) {

package/dist/mention-parse.d.ts

@@ -1,8 +1,2 @@
-export interface MentionCandidate {
-    /** The maximal name-grammar token after `@` (roster-free; resolution may shorten it). */
-    readonly token: string;
-    /** UTF-16 index of the `@` in the body. */
-    readonly index: number;
-}
-export declare function scanMentionCandidates(body: string): MentionCandidate[];
-export declare function resolveNameAt(body: string, candidate: MentionCandidate, names: readonly string[]): string | undefined;
+export declare function scanMentionCandidates(body: string): string[];
+export declare function resolveMention(text: string, names: readonly string[]): string | undefined;

package/dist/mention-parse.js

@@ -10,8 +10,8 @@ import { NAME_GRAPHEME_SOURCE, sameName } from './model.js';
  *   (`user@host`), URLs (`x.com/@user`), and `snake_@case` stay literal. Only ASCII
  *   word characters, `_`, `-`, `/`, and `@` block a boundary: CJK adjacency like
  *   `告诉@rei` stays mentionable because CJK text has no spaces to lean on.
- * - The token must be a complete name (slash-separated segments allowed); resolution
- *   never backs off to a shorter prefix, so `@rei2` does not mention `rei`.
+ * - Slash-separated names are allowed. Resolution may stop at a CJK suffix, but never
+ *   at an ASCII handle continuation: `@rei这个` can reach `rei`; `@rei2` cannot.
  */
 const MENTION_TOKEN = new RegExp(`@((?:${NAME_GRAPHEME_SOURCE})+(?:/(?:${NAME_GRAPHEME_SOURCE})+)*)`, 'vg');
 const BOUNDARY_BLOCKER = /[A-Za-z0-9_\-/@]/;
@@ -62,29 +62,26 @@ export function scanMentionCandidates(body) {
         const start = match.index;
         if (spans.some(([from, to]) => start >= from && start < to))
             continue;
-        const unit = start <= 0 ? undefined : body.charCodeAt(start - 1);
-        const previous = unit === undefined ? undefined
-            : unit >= 0xdc00 && unit <= 0xdfff && start >= 2 ? String.fromCodePoint(body.codePointAt(start - 2)) : String.fromCodePoint(unit);
+        const previous = body[start - 1];
         if (previous !== undefined && BOUNDARY_BLOCKER.test(previous))
             continue;
         const token = match[1];
         const key = token.toLocaleLowerCase();
         if (!seen.has(key)) {
             seen.add(key);
-            found.push({ token, index: start });
+            found.push(token);
         }
     }
     return found;
 }
 /**
- * Resolve the longest standing name starting at one candidate's position. A partial
+ * Resolve the longest standing name at the start of a candidate token. A partial
  * match is only accepted when the character right after it is not handle-continuation
  * (ASCII word char, `_`, `-`, `/`): `@rei2` never degrades into mentioning `rei`, while
  * CJK-fluent text like `告诉@rei这个` still mentions `rei`.
  */
 const TRAILING_BLOCKER = /[A-Za-z0-9_\-/]/;
-export function resolveNameAt(body, candidate, names) {
-    const text = body.slice(candidate.index + 1, candidate.index + 1 + candidate.token.length);
+export function resolveMention(text, names) {
     let best;
     for (const name of names) {
         if (name.length > text.length)

package/dist/model.d.ts

@@ -24,10 +24,14 @@ export interface SquareErrorFacts {
     reason?: 'never_joined' | 'not_standing' | 'bell_mention_conflict' | 'not_addressed' | 'migration_required' | 'explicit_reach_required' | 'invalid_reply' | 'invalid_done_body';
     /** The activity id a `catch --id` refusal named. */
     activityId?: string;
+    /** The host ledger requiring offline migration, rather than the selected artifact. */
+    ledgerRoot?: string;
     /** Requested recipient spellings, without parsing presentation copy. */
     targets?: readonly string[];
     /** Whether the artifact holds that activity at all; an unknown id needs an ordinary page. */
     activityExists?: boolean;
+    /** Express has a recipient, bell, body candidate, or explicit bare reach without its reply. */
+    hasReachWithoutReply?: boolean;
     pending?: number;
     holder?: string;
     holdReason?: string;
@@ -36,7 +40,7 @@ export interface SquareErrorFacts {
 declare class SquareErrorBase<Code extends string> extends Error {
     code: Code;
     facts?: SquareErrorFacts | undefined;
-    operation?: import('./square-facade.js').ApplicationFailureDetail;
+    operation?: import('./square-facade.js').OperationFailureDetail;
     constructor(code: Code, message: string, facts?: SquareErrorFacts | undefined);
 }
 export declare class SquareError extends SquareErrorBase<SquareErrorCode> {