@astrosheep/square 0.3.14 → 0.3.16

package/dist/delivery.js

@@ -1,36 +1,15 @@
-import path from 'node:path';
-import { SquareError, findParticipantName, sameName, } from './model.js';
-import { canonicalSquarePath, localParticipantName } from './registry.js';
-import { audienceOf, formatActivityId, resolveAudience } from './square-core.js';
-import { actId, isCurrentlyJoined, lastJoinIndex, matchesMentionTarget, resolveRosterName, rosterNames } from './runtime.js';
+import { findParticipantName, sameName, } from './model.js';
+import { audienceBefore, audienceOf, formatActivityId } from './square-core.js';
+import { isCurrentlyJoined, lastJoinIndex, matchesMentionTarget, observationFor, recordObservation, resolveRosterName, rosterNames } from './runtime.js';
 export function notificationMessageId(squarePath, actIndex) {
     return `square:${squarePath}#${formatActivityId(actIndex)}`;
 }
 function canonicalRecipient(squareState, name) {
     return resolveRosterName(squareState, name) ?? name;
 }
-/** Delivery receipts are the only durable acknowledgement of directed attention. */
-export function deliveryReceipt(squareState, name, actOrIndex) {
-    return deliveryReceiptFromRuntime(squareState.runtime, canonicalRecipient(squareState, name), actOrIndex);
-}
-export function deliveryReceiptFromRuntime(runtime, recipient, actOrIndex) {
-    return runtime.deliveryReceipts[recipient]?.[actId(actOrIndex)];
-}
-export function isDeliveryDelivered(squareState, name, actOrIndex) {
-    return deliveryReceipt(squareState, name, actOrIndex)?.status === 'delivered';
-}
-export function recordDeliveredDelivery(squareState, name, actOrIndex, receipt) {
-    return recordDeliveredRuntime(squareState.runtime, canonicalRecipient(squareState, name), actOrIndex, receipt);
-}
-export function recordDeliveredRuntime(runtime, recipient, actOrIndex, receipt) {
-    const id = actId(actOrIndex);
-    if (deliveryReceiptFromRuntime(runtime, recipient, actOrIndex)?.status === 'delivered')
-        return false;
-    (runtime.deliveryReceipts[recipient] ??= {})[id] = { status: 'delivered', ...receipt };
-    return true;
-}
-export function markDeliveredDelivery(squareState, name, actOrIndex, at = Date.now()) {
-    return recordDeliveredDelivery(squareState, name, actOrIndex, { at });
+export function isActivitySeen(squareState, name, actOrIndex) {
+    const index = typeof actOrIndex === 'number' ? actOrIndex : actOrIndex.index;
+    return observationFor(squareState, canonicalRecipient(squareState, name), index)?.state === 'seen';
 }
 /**
  * Derive delivery behavior once from the decoded Square state.
@@ -38,15 +17,25 @@ export function markDeliveredDelivery(squareState, name, actOrIndex, at = Date.n
  */
 export function deriveDeliveryModel(squareState) {
     const roster = rosterNames(squareState).filter((name) => isCurrentlyJoined(squareState.acts, name));
+    const plannedByIndex = new Map();
     let pendingByRecipient;
     function plan(item) {
         if (item.kind !== 'say')
             return [];
+        const cached = plannedByIndex.get(item.index);
+        if (cached !== undefined)
+            return [...cached];
         const sayItem = item;
         const audience = audienceOf(sayItem);
-        const recipients = resolveAudience(audience, roster).filter((recipient) => !sameName(recipient, sayItem.actor));
-        const route = audience.kind === 'bell' ? 'bell' : 'mention';
-        return recipients.map((recipient) => ({ item: sayItem, recipient, route }));
+        const recipients = audienceBefore(squareState.acts, sayItem);
+        const planned = recipients.map((recipient) => {
+            const route = audience.kind === 'bell'
+                ? 'bell'
+                : matchesMentionTarget(sayItem, recipient) ? 'mention' : 'attention';
+            return { item: sayItem, recipient, route };
+        });
+        plannedByIndex.set(item.index, planned);
+        return [...planned];
     }
     function pendingFor(requestedRecipient) {
         const recipient = findParticipantName(roster, requestedRecipient);
@@ -58,14 +47,11 @@ export function deriveDeliveryModel(squareState) {
             for (const act of squareState.acts) {
                 if (act.kind !== 'say')
                     continue;
-                const audience = audienceOf(act);
-                if (audience.kind === 'mentions' && audience.names.length === 0)
-                    continue;
                 for (const planned of plan(act)) {
                     const joinedAt = joinedAfter.get(planned.recipient);
                     if (joinedAt === undefined || act.index <= joinedAt)
                         continue;
-                    if (isDeliveryDelivered(squareState, planned.recipient, act.index))
+                    if (isActivitySeen(squareState, planned.recipient, act.index))
                         continue;
                     pendingByRecipient.get(planned.recipient)?.push(planned);
                 }
@@ -78,14 +64,21 @@ export function deriveDeliveryModel(squareState) {
 export function planActNotifications(squareState, item) {
     return deriveDeliveryModel(squareState).plan(item);
 }
-/** Mark only the directed notifications selected by the canonical pending projection. */
-export function markDeliveredNotifications(squareState, recipient, delivered, at = Date.now()) {
+export function perceiveActivity(squareState, item, viewer) {
+    if (item.kind !== 'say' || sameName(item.actor, viewer))
+        return 'full';
+    return deriveDeliveryModel(squareState).plan(item).some((planned) => sameName(planned.recipient, viewer))
+        ? 'full'
+        : 'presence';
+}
+/** Mark only the notifications selected by the canonical catch projection as fully seen. */
+export function markSeenNotifications(squareState, recipient, delivered, at = Date.now()) {
     const deliveredIndexes = new Set(delivered.map((item) => item.index));
     let changed = false;
     for (const notification of deriveDeliveryModel(squareState).pendingFor(recipient)) {
         if (!deliveredIndexes.has(notification.item.index))
             continue;
-        changed = recordDeliveredDelivery(squareState, notification.recipient, notification.item.index, { at }) || changed;
+        changed = recordObservation(squareState, notification.recipient, notification.item.index, 'seen', at) || changed;
     }
     return changed;
 }
@@ -97,49 +90,22 @@ export function matchesCatchFilter(activity, filter) {
         !filter.participants.some((participant) => sameName(participant, activity.actor))) {
         return false;
     }
-    return filter.mention === undefined || matchesMentionTarget(activity, filter.mention);
+    if (filter.mention === undefined)
+        return true;
+    return activity.recipients?.some((recipient) => sameName(recipient, filter.mention)) === true
+        || matchesMentionTarget(activity, filter.mention);
 }
 /** True only when the live catch's own filters would deliver this notification. */
 export function leaseOwnsNotification(lease, notification) {
+    if (lease.filter?.mention !== undefined
+        && notification.route !== 'bell'
+        && notification.recipient !== undefined
+        && !sameName(lease.filter.mention, notification.recipient))
+        return false;
     return matchesCatchFilter({
         actor: notification.actor,
         body: notification.body,
+        ...(notification.recipient === undefined ? {} : { recipients: [notification.recipient] }),
         ...(notification.route === 'bell' ? { reach: 'bell' } : {}),
     }, lease.filter ?? {});
 }
-const SQUARE_ROUTE_KEYS = ['name', 'squarePath', 'v'];
-function publicSquareFromCwd(cwd) {
-    return path.resolve(cwd, '.square', 'PUBLIC.square');
-}
-export function parseSquareRoute(value) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-        throw new SquareError('invalid_args', 'Malformed Square route');
-    }
-    const record = value;
-    const keys = Object.keys(record).sort();
-    if (keys.length !== SQUARE_ROUTE_KEYS.length || keys.some((key, index) => key !== SQUARE_ROUTE_KEYS[index])) {
-        throw new SquareError('invalid_args', 'Malformed Square route');
-    }
-    if (record.v !== 1 ||
-        typeof record.squarePath !== 'string' || record.squarePath === '' ||
-        typeof record.name !== 'string' || record.name === '') {
-        throw new SquareError('invalid_args', 'Malformed Square route');
-    }
-    return {
-        v: 1,
-        squarePath: record.squarePath,
-        name: record.name,
-    };
-}
-export function captureRoute(input) {
-    const env = input.env ?? process.env;
-    const squarePath = canonicalSquarePath(publicSquareFromCwd(input.cwd));
-    const name = localParticipantName(squarePath, env);
-    if (name === undefined)
-        return null;
-    return Object.freeze({
-        v: 1,
-        squarePath,
-        name,
-    });
-}

package/dist/help.js

@@ -18,12 +18,15 @@ const COMMANDS = [
     {
         names: ['express'], usage: '--as <name> express [-f|--force] [--no-wait] [--bell] [--reply <activity-id>] <activity | ->', usesSquare: true, group: 'participant',
         summary: 'Speak, gesture, or do both.',
-        details: ['Reach:', '  @name             Address someone in the square. They hear the body; everyone else sees you walk over.', "  --bell            Call every participant's attention to this activity without a mention.", '', 'Options:', '  -f, --force       Express without first catching unread activity.', '  --no-wait         If held or throttled, save a draft and return.', '  --reply <activity-id>   Mark this activity as a reply to an earlier activity (for example act/12).'],
+        details: ['Reach:', '  @name             Address someone in the square. They hear the body; everyone else sees you walk over.', "  --bell            Call every participant's attention to this activity without a mention.", '  listen             A participant turned toward you also hears your activity.', '', 'Options:', '  -f, --force       Express without first catching unread activity or attention etiquette.', '  --no-wait         If held or throttled, save a draft and return.', '  --reply <activity-id>   Mark this activity as a reply to an earlier activity (for example act/12).'],
     },
+    { names: ['listen'], usage: '--as <name> listen <participant>', usesSquare: true, group: 'participant', summary: 'Turn an ear toward one participant.' },
+    { names: ['ignore'], usage: '--as <name> ignore <participant>', usesSquare: true, group: 'participant', summary: 'Turn away from one participant.' },
+    { names: ['listening'], usage: '--as <name> listening', usesSquare: true, group: 'participant', summary: 'Show who you are turned toward.' },
     {
         names: ['catch'], usage: '--as <name> catch (--now | --idle <duration>) [--from <names>] [--mention [name]] [--replace]', usesSquare: true, group: 'participant',
         summary: 'Catch what others have said or done since you last looked.',
-        details: ['Modes:', '  --now             Catch up immediately.', '  --idle <duration> Wait for something relevant, or for quiet to last this long.', '', 'Filters:', '  --from <names>    Match only comma-separated participants.', '  --mention [name]  Match mentions of a name, or your own name when omitted.', '', 'Recovery:', '  --replace         Replace another active catch for this participant.'],
+        details: ['Modes:', '  --now             Catch up immediately.', '  --idle <duration> Wait for something relevant, or for quiet to last this long.', '', 'Filters:', '  --from <names>    Match only comma-separated participants.', '  --mention [name]  Match direct attention for a name, or your own name when omitted.', '', 'Recovery:', '  --replace         Replace another active catch for this participant.'],
     },
     { names: ['done'], usage: '--as <name> done [final | -]', usesSquare: true, group: 'participant', summary: 'Step out, optionally leaving a final note.' },
     {
@@ -40,7 +43,7 @@ const COMMANDS = [
     {
         names: ['history'], usage: '[--as <name>] history [filters] [output]', usesSquare: true, group: 'participant',
         summary: 'Read or search the archive without changing what you have caught.',
-        details: ['Filters:', '  --from <names>                  Match activities from participants.', '  --since <time>, --until <time>  Match a time window.', '  --grep <regex> | --fixed <s>    Search activity ids, participants, and original bodies.', '  --mention <name>                Match mentions.', '  --pending                       Match attention waiting for --as <name>.', '  --at <ids>                      Center on comma-separated activity ids; may repeat.', '  -B, -A, -C <N>                 Set non-negative context around every --at coordinate.', '  --after <id>                    Match activities after an id.', '', 'Results:', '  --limit <N> | --all             Bound the newest matches (default 10).', '  --order <asc|desc>              Set display order (default oldest first).', '', 'Output:', '  --full  --json  --format <fields>', '  Without --as, the default view shows complete activity bodies.'],
+        details: ['Filters:', '  --from <names>                  Match activities from participants.', '  --since <time>, --until <time>  Match a time window.', '  --grep <regex> | --fixed <s>    Search activity ids, participants, and original bodies.', '  --mention <name>                Match direct attention for a participant.', '  --pending                       Match attention waiting for --as <name>.', '  --at <ids>                      Center on comma-separated activity ids; may repeat.', '  -B, -A, -C <N>                 Set non-negative context around every --at coordinate.', '  --after <id>                    Match activities after an id.', '', 'Results:', '  --limit <N> | --all             Bound the newest matches (default 10).', '  --order <asc|desc>              Set display order (default oldest first).', '', 'Output:', '  --full  --json  --format <fields>', '  Without --as, the default view shows complete activity bodies.'],
     },
     { names: ['status'], usage: '[--as <name>] status', usesSquare: true, group: 'participant', summary: 'Show who is present and what happened most recently.' },
     { names: ['participants'], usage: 'participants', usesSquare: true, group: 'host', summary: 'Show the full participant roster and current states.' },
@@ -74,7 +77,7 @@ function isHelpFlag(value) {
 }
 export function renderGlobalHelp() {
     const groups = [
-        { key: 'participant', title: 'In the square:', order: ['join', 'express', 'catch', 'history', 'status', 'hold', 'resume', 'done'] },
+        { key: 'participant', title: 'In the square:', order: ['join', 'express', 'listen', 'ignore', 'listening', 'catch', 'history', 'status', 'hold', 'resume', 'done'] },
         { key: 'host', title: 'Prepare and manage:', order: ['build', 'list', 'participants'] },
         { key: 'maintenance', title: 'Setup:', order: ['install', 'uninstall', 'doctor'] },
     ];
@@ -88,7 +91,7 @@ export function renderGlobalHelp() {
     ]);
     return [
         'Usage: square [--location <square>] [--as <name>] <command> [args...]',
-        'Environment: SQUARE_LOCATION sets the CLI location; SQUARE_PARTICIPANT_NAME sets the participant name.',
+        'Environment: SQUARE_LOCATION sets the CLI location; square-accessing commands require it or --location. SQUARE_PARTICIPANT_NAME sets the participant name.',
         'CLI flags override environment values. Automatic provider sessions use only .square/PUBLIC.square.',
         '',
         ...commandLines,

package/dist/inbox.js

@@ -14,6 +14,7 @@ export async function sessionInbox(sessionId) {
             inbox.push({
                 name: projection.name,
                 squarePath: binding.squarePath,
+                ownerId: binding.ownerId,
                 notifications: [...projection.notifications],
                 ...(projection.catchLease !== undefined ? { catchLease: projection.catchLease } : {}),
             });

package/dist/index.d.ts

@@ -1,13 +1,4 @@
-import { type SquareRoute } from './delivery.js';
-import type { ExpressResult } from './square-facade.js';
 export { Square } from './square-wiring.js';
 export { SquareError } from './model.js';
-export { captureRoute } from './delivery.js';
-export type { SquareRoute } from './delivery.js';
 export type { ActivityId } from './square-core.js';
-export type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, HistoryQuery, OpenOptions, Participant, ParticipantStatus, PerceivedActivity, SquareAtInput, SquareBuildInput, SquareSnapshot, SquareSource, WakeNotifier, } from './square-facade.js';
-export interface RouteExpressOptions {
-    readonly as: string;
-    readonly body: string;
-}
-export declare function express(route: SquareRoute, options: RouteExpressOptions): Promise<ExpressResult>;
+export type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, HistoryQuery, ListenerChangeResult, OpenOptions, Participant, ParticipantStatus, PerceivedActivity, SquareAtInput, SquareBuildInput, SquareSnapshot, SquareSource, WakeNotifier, } from './square-facade.js';

package/dist/index.js

@@ -1,34 +1,2 @@
-import { extractMentions } from './square-core.js';
-import { parseSquareRoute } from './delivery.js';
-import { sameName, SquareError } from './model.js';
-import { Square } from './square-wiring.js';
-import { wakeNotifierForSquare } from './notifications.js';
 export { Square } from './square-wiring.js';
 export { SquareError } from './model.js';
-export { captureRoute } from './delivery.js';
-function directedBody(body, recipient) {
-    if (body.trim() === '')
-        throw new SquareError('invalid_args', 'express body cannot be empty');
-    if (extractMentions(body).some((mention) => sameName(mention, recipient)))
-        return body;
-    return `${body}${/\s$/u.test(body) ? '' : ' '}@${recipient}`;
-}
-export async function express(route, options) {
-    const parsed = parseSquareRoute(route);
-    if (options === null || typeof options !== 'object' ||
-        typeof options.as !== 'string' || options.as.trim() === '' ||
-        typeof options.body !== 'string') {
-        throw new SquareError('invalid_args', 'Route express requires { as, body }');
-    }
-    const square = await Square.at({ path: parsed.squarePath, notifier: wakeNotifierForSquare(parsed.squarePath) });
-    try {
-        const recipient = (await square.participants()).find((participant) => participant.state === 'joined' && sameName(participant.name, parsed.name));
-        if (recipient === undefined)
-            throw new SquareError('invalid_args', `Unknown participant "${parsed.name}"`);
-        const sender = await square.join(options.as);
-        return sender.express(directedBody(options.body, recipient.name));
-    }
-    finally {
-        await square.close();
-    }
-}

package/dist/landing.d.ts

@@ -4,7 +4,19 @@ export declare function join(square: OpenSquare, name: string): Promise<{
     readonly name: string;
     readonly activity: Activity | null;
 }>;
+/** Automatic presence distinguishes first entry, current presence, and completed presence. */
+export declare function implicitJoin(square: OpenSquare, name: string): Promise<{
+    readonly name: string;
+    readonly state: 'joined' | 'active' | 'done';
+    readonly activity: Activity | null;
+}>;
 export declare function express(square: OpenSquare, name: string, body: string, options?: ExpressOptions): Promise<ExpressResult>;
+export interface ListenerChangeResult {
+    readonly activity: Activity | null;
+}
+export declare function listen(square: OpenSquare, actor: string, target: string): Promise<ListenerChangeResult>;
+export declare function ignore(square: OpenSquare, actor: string, target: string): Promise<ListenerChangeResult>;
+export declare function listening(square: OpenSquare, actor: string): Promise<readonly string[]>;
 export declare function done(square: OpenSquare, name: string, body?: string): Promise<ExpressResult>;
 export declare function hold(square: OpenSquare, name: string, reason?: string): Promise<ExpressResult>;
 export declare function resume(square: OpenSquare, name: string): Promise<ExpressResult>;

package/dist/landing.js

@@ -1,17 +1,14 @@
 import { extractMentions, formatActivityId, parseActivityId } from './square-core.js';
-import { coreDone, coreHold, coreResume, decideAct, decideJoin } from './decisions.js';
+import { coreDone, coreHold, coreIgnore, coreListen, coreListening, coreResume, decideAct, decideImplicitJoin, decideJoin } from './decisions.js';
 import { deriveDeliveryModel } from './delivery.js';
 import { SquareError } from './model.js';
 import { participantIdentity } from './participant-identity.js';
-import { touchPresenceCursor } from './runtime.js';
 function storeActs(state, acts) {
     const stored = [];
     for (const act of acts) {
         const item = { ...act, index: state.runtime.nextActIndex };
         state.runtime.nextActIndex += 1;
         state.acts.push(item);
-        if (item.actor !== undefined)
-            touchPresenceCursor(state, item.actor, item.at, item.index);
         stored.push(item);
     }
     return stored;
@@ -29,6 +26,7 @@ function exposeActivity(stored) {
         id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor,
         ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}),
         mentions: stored.kind === 'say' ? extractMentions(stored.body) : [],
+        ...('target' in stored ? { target: stored.target } : {}),
         ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}),
     };
 }
@@ -56,6 +54,17 @@ export async function join(square, name) {
     });
     return { name: committed.name, activity: committed.stored === null ? null : exposeActivity(committed.stored) };
 }
+/** Automatic presence distinguishes first entry, current presence, and completed presence. */
+export async function implicitJoin(square, name) {
+    const now = square.clock();
+    const committed = await square.cell.transact((state) => {
+        const decision = decideImplicitJoin(state, name, now);
+        if (decision.joinAct === undefined)
+            return { result: { name: decision.joinedName, state: decision.state, stored: null } };
+        return { state, result: { name: decision.joinedName, state: decision.state, stored: committedActivity(storeActs(state, [decision.joinAct]), 'join') } };
+    });
+    return { name: committed.name, state: committed.state, activity: committed.stored === null ? null : exposeActivity(committed.stored) };
+}
 export async function express(square, name, body, options = {}) {
     const now = square.clock();
     const reply = options.reply === undefined ? undefined : parseRequiredActivityId(options.reply);
@@ -82,6 +91,28 @@ export async function express(square, name, body, options = {}) {
     await wakeAfterCommit(square, committed.recipients, activity);
     return { activity };
 }
+async function landListenerChange(square, verb, actor, target) {
+    const now = square.clock();
+    const stored = await square.cell.transact((state) => {
+        const act = verb === 'listen'
+            ? coreListen(state, actor, target, now)
+            : coreIgnore(state, actor, target, now);
+        if (act === undefined)
+            return { result: null };
+        return { state, result: committedActivity(storeActs(state, [act]), verb) };
+    });
+    return { activity: stored === null ? null : exposeActivity(stored) };
+}
+export function listen(square, actor, target) {
+    return landListenerChange(square, 'listen', actor, target);
+}
+export function ignore(square, actor, target) {
+    return landListenerChange(square, 'ignore', actor, target);
+}
+export async function listening(square, actor) {
+    const { state } = await square.cell.read();
+    return coreListening(state, actor);
+}
 async function landCore(square, verb, actor, body = '') {
     const now = square.clock();
     const stored = await square.cell.transact((state) => {

package/dist/model.d.ts

@@ -40,14 +40,11 @@ export type StoredAct = Act & {
     at: number;
 };
 export type StoredActHead = StoredAct extends infer T ? T extends StoredAct ? Omit<T, 'body' | 'through' | 'index'> : never : never;
-export interface ReadCursor {
-    consumedThroughIndex: number;
-    updatedAt: number;
-}
-export interface DeliveryReceipt {
-    /** Inject presentation lives only in the machine-local presented ledger. */
-    status: 'delivered';
+export type ObservationState = 'notified' | 'seen';
+export interface ActivityObservation {
+    state: ObservationState;
     at: number;
+    ownerId?: string;
 }
 export interface WatchLeaseFilter {
     participants?: string[];
@@ -61,7 +58,7 @@ export interface WatchLease {
     expiresAt: number;
     filter?: WatchLeaseFilter;
 }
-export type DirectedNotificationRoute = 'mention' | 'bell';
+export type DirectedNotificationRoute = 'mention' | 'attention' | 'bell';
 export interface InboxNotification {
     actIndex: number;
     actor: string;
@@ -72,6 +69,7 @@ export interface InboxNotification {
 export interface InboxMembership {
     name: string;
     squarePath: string;
+    ownerId?: string;
     notifications: InboxNotification[];
     catchLease?: WatchLease;
 }
@@ -84,8 +82,7 @@ export interface NotifyLease {
 }
 export interface SquareRuntimeState {
     nextActIndex: number;
-    cursors: Record<string, ReadCursor>;
-    deliveryReceipts: Record<string, Record<string, DeliveryReceipt>>;
+    observations: Record<string, Record<string, ActivityObservation>>;
     leases: Record<string, WatchLease>;
     notifyLeases: Record<string, NotifyLease>;
 }
@@ -132,7 +129,7 @@ export type PublicAct = Extract<StoredAct, {
     kind: 'say' | 'done';
 }>;
 export type RoomChangeAct = Extract<StoredAct, {
-    kind: 'join' | 'done' | 'hold' | 'resume';
+    kind: 'join' | 'done' | 'hold' | 'resume' | 'listen' | 'ignore';
 }>;
 export interface HoldState {
     active: boolean;

package/dist/model.js

@@ -40,7 +40,7 @@ export function findParticipantName(participants, name) {
     return participants.find((participant) => sameName(participant, name));
 }
 export function validateName(name) {
-    if (!name || !/^[\p{L}\p{N}_-]+$/u.test(name)) {
-        throw new SquareError('invalid_name', 'Invalid name: names must be non-empty and can only contain Unicode letters, digits, hyphens, and underscores.');
+    if (!name || !/^[\p{L}\p{N}_-]+(?:\/[\p{L}\p{N}_-]+)*$/u.test(name)) {
+        throw new SquareError('invalid_name', 'Invalid name: names must contain non-empty slash-separated segments using only Unicode letters, digits, hyphens, and underscores.');
     }
 }

package/dist/notifications.js

@@ -1,6 +1,5 @@
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { homedir } from 'node:os';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 import { leaseOwnsNotification, planActNotifications, } from './delivery.js';
@@ -9,10 +8,13 @@ import { hasPresentedAttention } from './presented.js';
 import { SquareError } from './model.js';
 import { SLEEP_MS, matchesMentionTarget } from './runtime.js';
 import { parseActivityId } from './square-core.js';
-import { PaseoAdapter } from './paseo-delivery.js';
-import { participantIdentity, quoteShell } from './presentation.js';
+import { quoteShell } from './presentation.js';
+import { renderAttentionPreview } from './attention-presentation.js';
 import { lookupParticipant } from './registry.js';
+import { retireWakeRoute } from './routes.js';
+import { recordPresentedForOwner } from './presented.js';
 import { openSquare } from './square-file-adapter.js';
+import { markNotificationNotified } from './square-wiring.js';
 import { closeOpenSquare } from './open-square.js';
 import { entryPresentation, notificationDelivered, notificationForAct, pendingDeliveries, resolveParticipant } from './views.js';
 import { claimNotificationLease, releaseNotificationLease, transitionNotificationLease } from './wakes.js';
@@ -32,14 +34,18 @@ export function wakeGraceMs(env = process.env) {
 function catchCommand(squarePath, recipient) {
     return `square --as ${quoteShell(recipient)} --location ${quoteShell(squarePath)} catch --now`;
 }
-function renderWakePayload(request) {
-    const display = request.squarePath.startsWith(homedir())
-        ? `~${request.squarePath.slice(homedir().length)}`
-        : request.squarePath;
+function renderWakePayload(request, body) {
     return [
         '<system-reminder source="square">',
-        `${request.route === 'bell' ? 'Bell' : 'Mention'} from ${participantIdentity(request.actor)} in \`${display}\``,
-        'The native adapter will present it at the next boundary. If no native wake is available, pull from the square yourself.',
+        renderAttentionPreview({
+            squarePath: request.squarePath,
+            actIndex: request.actIndex,
+            recipient: request.recipient,
+            actor: request.actor,
+            route: request.route,
+            body,
+        }),
+        'The native adapter presented this attention. If you have not acted on it, pull from the square yourself.',
         `\`${catchCommand(request.squarePath, request.recipient)}\``,
         '</system-reminder>',
     ].join('\n');
@@ -53,6 +59,7 @@ async function waitForCatch(route, request, body) {
         actor: request.actor,
         body,
         route: request.route,
+        recipient: request.recipient,
     }))
         return false;
     const deadline = Date.now() + 180_000;
@@ -107,6 +114,16 @@ export async function waitForDeliveredNotification(squarePath, name, ref, opts =
     }
     return false;
 }
+async function defaultWakeAdapters() {
+    try {
+        const { PaseoAdapter } = await import('./paseo-delivery.js');
+        return [new PaseoAdapter()];
+    }
+    catch {
+        // Paseo is an optional integration; a core-only install simply has no Paseo adapter.
+        return [];
+    }
+}
 async function claimNotifyLease(square, recipient, actIndex) {
     const leaseId = randomUUID();
     return claimNotificationLease(square, recipient, actIndex, leaseId, NOTIFY_LEASE_MS);
@@ -149,7 +166,7 @@ async function processNotification(squarePath, notification, opts) {
         const evidence = await wakeEvidence(squarePath, notification.recipient, notification.item.index, dispatchAt, env);
         if (!wakeIsEligible(evidence))
             return;
-        const port = new WakePort(opts.adapters ?? [new PaseoAdapter()]);
+        const port = new WakePort(opts.adapters ?? await defaultWakeAdapters());
         const request = {
             squarePath,
             actIndex: notification.item.index,
@@ -157,7 +174,7 @@ async function processNotification(squarePath, notification, opts) {
             actor: notification.item.actor,
             route: notification.route,
         };
-        await port.dispatch(evidence.attemptableRoutes, renderWakePayload(request), {
+        await port.dispatch(evidence.attemptableRoutes, renderWakePayload(request, notification.item.body), {
             nextAttemptN: () => nextWakeAttemptNumber(attention, { env, now: now() }),
             beforeSend: async (route, attemptN) => {
                 if (await waitForCatch(route, request, notification.item.body))
@@ -190,9 +207,16 @@ async function processNotification(squarePath, notification, opts) {
                     ...('message' in outcome ? { message: outcome.message } : {}),
                     ...('diagnostic' in outcome && outcome.diagnostic !== undefined ? { diagnostic: outcome.diagnostic } : {}),
                 }, env);
+                if (outcome.outcome === 'accepted') {
+                    await markNotificationNotified(square, notification.recipient, notification.item.index, route.ownerId, now());
+                    recordPresentedForOwner(route.ownerId, squarePath, notification.recipient, notification.item.index, env, now());
+                }
                 if (outcome.outcome !== 'failed')
                     releaseLease = true;
             },
+            invalidate: async (route) => {
+                retireWakeRoute(route, { env, at: now() });
+            },
         });
     }
     finally {

package/dist/paseo-delivery.js

@@ -34,7 +34,7 @@ export class PaseoAdapter {
         const agentId = address.agentId?.trim();
         if (!agentId) {
             return {
-                outcome: 'failed',
+                outcome: 'unavailable',
                 signature: 'invalid_address',
                 message: 'Paseo route has no agent id.',
                 diagnostic: diagnostic('selection', address, 'invalid_address'),
@@ -43,27 +43,30 @@ export class PaseoAdapter {
         const discovery = (this.opts.discover ?? discoverPaseoAgents)();
         if (discovery.error && discovery.agents.length === 0) {
             return {
-                outcome: 'failed',
+                outcome: 'unavailable',
                 signature: discoveryRetryable(discovery.error) ? 'discovery_transient' : 'discovery_rejected',
                 message: `Paseo unavailable: ${discovery.error}`,
                 diagnostic: diagnostic('discovery', address, 'unavailable'),
+                retainRoute: true,
             };
         }
         const agent = discovery.agents.find((candidate) => candidate.id === agentId);
         if (agent === undefined || (agent.status !== 'idle' && agent.status !== 'running')) {
             return {
-                outcome: 'failed',
+                outcome: 'unavailable',
                 signature: agent === undefined ? 'address_not_found' : 'agent_not_active',
                 message: agent === undefined ? 'The registered Paseo agent was not found.' : 'The registered Paseo agent is not idle or running.',
                 diagnostic: diagnostic('selection', address, agent === undefined ? 'not_found' : 'not_active'),
+                ...(agent === undefined ? {} : { retainRoute: true }),
             };
         }
         if (!(await (this.opts.waitForBoundary ?? waitForPaseoWakeBoundary)(agent))) {
             return {
-                outcome: 'failed',
+                outcome: 'unavailable',
                 signature: 'boundary_unavailable',
                 message: 'Paseo did not reach the current tool boundary before the wake timeout.',
                 diagnostic: diagnostic('boundary', address, 'unavailable'),
+                retainRoute: true,
             };
         }
         if (!(await beforeSend()))

package/dist/paseo.d.ts

@@ -0,0 +1,6 @@
+/** Optional Paseo integration. Importing this entry requires the Paseo peer dependencies. */
+export { PaseoAdapter } from './paseo-delivery.js';
+export { PaseoWakeSendError, sendPaseoWake } from './wake-sink.js';
+export { connectPaseoDaemon, paseoDaemonHosts, resolvePaseoDaemonTarget, } from './paseo-connection.js';
+export { discoverPaseoAgents, waitForPaseoWakeBoundary } from './paseo-state.js';
+export type { PaseoAgent } from './paseo-state.js';

package/dist/paseo.js

@@ -0,0 +1,5 @@
+/** Optional Paseo integration. Importing this entry requires the Paseo peer dependencies. */
+export { PaseoAdapter } from './paseo-delivery.js';
+export { PaseoWakeSendError, sendPaseoWake } from './wake-sink.js';
+export { connectPaseoDaemon, paseoDaemonHosts, resolvePaseoDaemonTarget, } from './paseo-connection.js';
+export { discoverPaseoAgents, waitForPaseoWakeBoundary } from './paseo-state.js';

package/dist/presence.d.ts

@@ -1,3 +1,6 @@
 import type { OpenSquare } from './open-square.js';
 import type { CatchOptions, CatchResult } from './square-facade.js';
 export declare function catchUp(square: OpenSquare, name: string, options?: CatchOptions): Promise<CatchResult>;
+/** Commit seen only for complete, actually rendered boundary bodies. */
+export declare function markBoundarySeen(squarePath: string, name: string, ownerId: string | undefined, actIndexes: readonly number[], at?: number): Promise<void>;
+export declare function markNotificationNotified(square: OpenSquare, name: string, actIndex: number, ownerId: string | undefined, at?: number): Promise<void>;