@astrosheep/square 0.3.14 → 0.3.16

package/dist/cli/square-commands.js

@@ -6,9 +6,9 @@ import { sweepPendingNotifications, wakeNotifierForSquare } from '../notificatio
 import { nowMs } from '../runtime.js';
 import { createSquare, openSquare } from '../square-file-adapter.js';
 import { closeOpenSquare } from '../open-square.js';
-import { Square } from '../square-wiring.js';
-import { entryPresentation, eventPresentation } from '../views.js';
-import { fail, parseHardCap, parsePositiveInteger, readPipedBodyFallback, readStdinSync, requireParticipant, requireValue, resolveBody, usage, } from './context.js';
+import { openParticipant, Square } from '../square-wiring.js';
+import { admitsBareExpress, entryPresentation, eventPresentation } from '../views.js';
+import { fail, parseHardCap, parsePositiveInteger, readPipedBodyFallback, readStdinSync, requireParticipant, requireSquarePath, requireValue, resolveBody, usage, } from './context.js';
 function parseBuild(argv) {
     const options = { force: false, hardCap: null };
     for (let index = 0; index < argv.length; index++) {
@@ -49,10 +49,11 @@ function parseBuild(argv) {
 export const buildCommand = {
     parse: (argv) => parseBuild(argv),
     async execute(intent, context) {
-        await createSquare(context.squarePath, intent.options, intent.snippet);
+        const squarePath = requireSquarePath(context);
+        await createSquare(squarePath, intent.options, intent.snippet);
         const cap = intent.options.hardCap === null ? 'unlimited' : formatHardCap(intent.options.hardCap);
         const throttle = intent.options.throttlePerMinute === undefined ? [] : [`  · throttle ${intent.options.throttlePerMinute}/min`];
-        return withPathOutput(context.squarePath, ['✓ built', `  · cap ${cap}`, ...throttle, '  · participants (none seeded — first join adds names)'].join('\n'), { participantCount: 0 });
+        return withPathOutput(squarePath, ['✓ built', `  · cap ${cap}`, ...throttle, '  · participants (none seeded — first join adds names)'].join('\n'), { participantCount: 0 });
     },
     present: (result) => process.stdout.write(result),
 };
@@ -79,38 +80,40 @@ function parseJoin(argv, context) {
 export const joinCommand = {
     parse: parseJoin,
     async execute(intent, context) {
-        const beforeSquare = await openSquare(context.squarePath, { clock: nowMs });
+        const squarePath = requireSquarePath(context);
+        const beforeSquare = await openSquare(squarePath, { clock: nowMs });
         const before = await entryPresentation(beforeSquare, intent.name, intent.lastN);
         await closeOpenSquare(beforeSquare);
-        const square = await Square.at({ path: context.squarePath, clock: nowMs, notifier: wakeNotifierForSquare(context.squarePath) });
+        const square = await Square.at({ path: squarePath, clock: nowMs, notifier: wakeNotifierForSquare(squarePath) });
         try {
             const participant = await square.join(intent.name);
             const joinedName = participant.name;
             const isRejoin = before.joined;
             const reconnect = isRejoin
-                && localParticipantOwner(context.squarePath, joinedName) !== undefined;
+                && localParticipantOwner(squarePath, joinedName) !== undefined;
             if (isRejoin && !intent.kick && !reconnect) {
                 fail([
                     `✕ ${participantIdentity(joinedName)} shoos you out of the square`,
                     `  · a same-named participant stands here — the name is taken`,
                     `  · --kick banishes her and the name becomes yours`,
-                    `» ${participantCommandPrefix(context.squarePath, joinedName)} join --kick`,
+                    `» ${participantCommandPrefix(squarePath, joinedName)} join --kick`,
                 ].join('\n'));
             }
-            const afterSquare = await openSquare(context.squarePath, { clock: nowMs });
+            const afterSquare = await openSquare(squarePath, { clock: nowMs });
             const after = await entryPresentation(afterSquare, joinedName, intent.lastN);
             await closeOpenSquare(afterSquare);
-            recordLocalJoin(joinedName, context.squarePath);
-            await sweepPendingNotifications(context.squarePath);
+            recordLocalJoin(joinedName, squarePath);
+            await sweepPendingNotifications(squarePath);
             const activities = after.recentActivities.map((event) => renderAmbientEvent(event, joinedName, {
                 now: nowMs(),
                 preview: intent.lastN === null ? undefined : 200,
                 actNumber: event.kind === 'say' ? after.sayNumbers[event.index] : undefined,
+                squareState: after.state,
             })).filter(Boolean).join('\n\n');
             const contextText = after.joinContext;
             const fallback = hasAutomaticDeliveryIdentity()
                 ? []
-                : ['', `» ${participantCommandPrefix(context.squarePath, joinedName)} catch --idle 30m`, '  no session delivery detected — keep this catch open for new activity'];
+                : ['', `» ${participantCommandPrefix(squarePath, joinedName)} catch --idle 30m`, '  no session delivery detected — keep this catch open for new activity'];
             const scene = after.scene;
             const entryLine = !isRejoin
                 ? '● You stepped into the square'
@@ -124,7 +127,7 @@ export const joinCommand = {
                 ...(isRejoin || activities === '' ? [] : ['', 'recent activity', activities]),
                 ...fallback,
             ].join('\n');
-            return withPathOutput(context.squarePath, output, { participantCount: after.participantCount });
+            return withPathOutput(squarePath, output, { participantCount: after.participantCount });
         }
         finally {
             await square.close();
@@ -172,18 +175,108 @@ function parseActivity(argv, context) {
 export const expressCommand = {
     parse: parseActivity,
     async execute(intent, context) {
-        await sweepPendingNotifications(context.squarePath);
+        const squarePath = requireSquarePath(context);
+        await sweepPendingNotifications(squarePath);
+        const body = resolveBody(intent.activity);
+        if (!intent.force && intent.reach !== 'bell') {
+            const reader = await openSquare(squarePath, { clock: nowMs });
+            try {
+                if (!await admitsBareExpress(reader, intent.name, body)) {
+                    fail(`✕ no one is turned toward you\n  · address someone with @name, ring the bell, or use --force\n» ${participantCommandPrefix(squarePath, intent.name)} express --force -`);
+                }
+            }
+            finally {
+                await closeOpenSquare(reader);
+            }
+        }
         const reachArg = intent.reach === 'bell' ? ' --bell' : '';
-        await cmdActivity(context.squarePath, intent.name, intent.activity, resolveBody, {
+        await cmdActivity(squarePath, intent.name, body, (value) => value, {
             force: intent.force,
             noWait: intent.noWait,
             reach: intent.reach,
             reply: intent.reply,
-            forceCommand: `${participantCommandPrefix(context.squarePath, intent.name)} express --force${reachArg}${intent.reply === undefined ? '' : ` --reply ${formatActivityId(intent.reply)}`} -`,
+            forceCommand: `${participantCommandPrefix(squarePath, intent.name)} express --force${reachArg}${intent.reply === undefined ? '' : ` --reply ${formatActivityId(intent.reply)}`} -`,
         });
     },
     present: () => { },
 };
+function parseListener(argv, context, targetRequired) {
+    if (targetRequired ? argv.length !== 1 : argv.length !== 0)
+        usage(context.command);
+    return { name: requireParticipant(context.name), ...(targetRequired ? { target: argv[0] } : {}) };
+}
+function listenerPresentation(squarePath, actor, target, verb, activity, participantCount) {
+    if (activity !== null) {
+        const action = verb === 'listen'
+            ? `${participantIdentity(actor)} turns an ear toward ${participantIdentity(target)}`
+            : `${participantIdentity(actor)} turns away from ${participantIdentity(target)}`;
+        return withPathOutput(squarePath, `· ${action}`, { participantCount });
+    }
+    const action = verb === 'listen'
+        ? `${participantIdentity(actor)} already turns an ear toward ${participantIdentity(target)}`
+        : `${participantIdentity(actor)} is not turned toward ${participantIdentity(target)}`;
+    return withPathOutput(squarePath, `○ ${action}`, { participantCount });
+}
+export const listenCommand = {
+    parse(argv, context) { return parseListener(argv, context, true); },
+    async execute(intent, context) {
+        const squarePath = requireSquarePath(context);
+        const square = await Square.at({ path: squarePath, clock: nowMs });
+        const facade = await openParticipant({ path: squarePath, clock: nowMs }, intent.name);
+        try {
+            const participant = facade.participant;
+            const result = await participant.listen(intent.target);
+            const participantCount = (await square.snapshot()).participants.filter((item) => item.state === 'joined').length;
+            return listenerPresentation(squarePath, participant.name, intent.target, 'listen', result.activity, participantCount);
+        }
+        finally {
+            await facade.close();
+            await square.close();
+        }
+    },
+    present: (result) => process.stdout.write(result),
+};
+export const ignoreCommand = {
+    parse(argv, context) { return parseListener(argv, context, true); },
+    async execute(intent, context) {
+        const squarePath = requireSquarePath(context);
+        const square = await Square.at({ path: squarePath, clock: nowMs });
+        const facade = await openParticipant({ path: squarePath, clock: nowMs }, intent.name);
+        try {
+            const participant = facade.participant;
+            const result = await participant.ignore(intent.target);
+            const participantCount = (await square.snapshot()).participants.filter((item) => item.state === 'joined').length;
+            return listenerPresentation(squarePath, participant.name, intent.target, 'ignore', result.activity, participantCount);
+        }
+        finally {
+            await facade.close();
+            await square.close();
+        }
+    },
+    present: (result) => process.stdout.write(result),
+};
+export const listeningCommand = {
+    parse(argv, context) { return parseListener(argv, context, false); },
+    async execute(intent, context) {
+        const squarePath = requireSquarePath(context);
+        const square = await Square.at({ path: squarePath, clock: nowMs });
+        const facade = await openParticipant({ path: squarePath, clock: nowMs }, intent.name);
+        try {
+            const participant = facade.participant;
+            const targets = await participant.listening();
+            const participantCount = (await square.snapshot()).participants.filter((item) => item.state === 'joined').length;
+            const body = targets.length === 0
+                ? `○ ${participantIdentity(participant.name)} is not turned toward anyone`
+                : ['listening', ...targets.map((target) => `  · ${participantIdentity(target)}`)].join('\n');
+            return withPathOutput(squarePath, body, { participantCount });
+        }
+        finally {
+            await facade.close();
+            await square.close();
+        }
+    },
+    present: (result) => process.stdout.write(result),
+};
 function parseDone(argv, context) {
     if (argv.length > 1)
         usage(context.command);
@@ -192,16 +285,17 @@ function parseDone(argv, context) {
 export const doneCommand = {
     parse: parseDone,
     async execute(intent, context) {
+        const squarePath = requireSquarePath(context);
         const body = resolveBody(intent.body ?? '').replace(/\r\n/g, '\n').trim();
-        const square = await Square.at({ path: context.squarePath, clock: nowMs, notifier: wakeNotifierForSquare(context.squarePath) });
+        const square = await Square.at({ path: squarePath, clock: nowMs, notifier: wakeNotifierForSquare(squarePath) });
         const participant = await square.join(intent.name);
         const result = await participant.done(body);
         await square.close();
         const name = result.activity.actor;
-        recordLocalDone(name, context.squarePath);
-        const presentation = await openSquare(context.squarePath, { clock: nowMs });
+        recordLocalDone(name, squarePath);
+        const presentation = await openSquare(squarePath, { clock: nowMs });
         const participantCount = (await entryPresentation(presentation, name).finally(() => closeOpenSquare(presentation))).participantCount;
-        return withPathOutput(context.squarePath, `○ ${participantIdentity(name)} steps out of the square — done · just now`, { participantCount });
+        return withPathOutput(squarePath, `○ ${participantIdentity(name)} steps out of the square — done · just now`, { participantCount });
     },
     present: (result) => process.stdout.write(result),
 };
@@ -213,15 +307,16 @@ function parseHold(argv, context) {
 export const holdCommand = {
     parse: parseHold,
     async execute(intent, context) {
-        const square = await Square.at({ path: context.squarePath, clock: nowMs, notifier: wakeNotifierForSquare(context.squarePath) });
+        const squarePath = requireSquarePath(context);
+        const square = await Square.at({ path: squarePath, clock: nowMs, notifier: wakeNotifierForSquare(squarePath) });
         try {
             const participant = await square.join(intent.name);
             const result = await participant.hold(resolveBody(intent.body ?? '').replace(/\r\n/g, '\n').trim());
             await square.close();
-            const presentationSquare = await openSquare(context.squarePath, { clock: nowMs });
+            const presentationSquare = await openSquare(squarePath, { clock: nowMs });
             const presentation = await eventPresentation(presentationSquare, result.activity.id);
             await closeOpenSquare(presentationSquare);
-            return withPathOutput(context.squarePath, renderEventCli(presentation.activity), { participantCount: presentation.participantCount, held: true });
+            return withPathOutput(squarePath, renderEventCli(presentation.activity), { participantCount: presentation.participantCount, held: true });
         }
         finally {
             await square.close();
@@ -236,15 +331,16 @@ export const resumeCommand = {
         return { name: requireParticipant(context.name) };
     },
     async execute(intent, context) {
-        const square = await Square.at({ path: context.squarePath, clock: nowMs, notifier: wakeNotifierForSquare(context.squarePath) });
+        const squarePath = requireSquarePath(context);
+        const square = await Square.at({ path: squarePath, clock: nowMs, notifier: wakeNotifierForSquare(squarePath) });
         try {
             const participant = await square.join(intent.name);
             const result = await participant.resume();
             await square.close();
-            const presentationSquare = await openSquare(context.squarePath, { clock: nowMs });
+            const presentationSquare = await openSquare(squarePath, { clock: nowMs });
             const presentation = await eventPresentation(presentationSquare, result.activity.id);
             await closeOpenSquare(presentationSquare);
-            return withPathOutput(context.squarePath, renderEventCli(presentation.activity), { participantCount: presentation.participantCount });
+            return withPathOutput(squarePath, renderEventCli(presentation.activity), { participantCount: presentation.participantCount });
         }
         finally {
             await square.close();

package/dist/codex-hook.js

@@ -32,11 +32,12 @@ export async function runCodexHookAsync(inputText, env = process.env) {
     if (input === null || typeof input !== 'object')
         return '';
     const value = input;
-    if (typeof value.session_id !== 'string' || typeof value.cwd !== 'string')
+    if (typeof value.session_id !== 'string')
         return runCodexHook(inputText, env);
     if (value.hook_event_name === 'SessionStart' || value.hook_event_name === 'SessionResume') {
+        const cwd = typeof value.cwd === 'string' ? value.cwd : process.cwd();
         try {
-            const context = await automaticSessionStart('codex', value.session_id, value.cwd, env);
+            const context = await automaticSessionStart('codex', value.session_id, cwd, env);
             return context === undefined ? '' : `${JSON.stringify({ hookSpecificOutput: { hookEventName: value.hook_event_name, additionalContext: context } })}\n`;
         }
         catch {
@@ -44,8 +45,9 @@ export async function runCodexHookAsync(inputText, env = process.env) {
         }
     }
     if (value.hook_event_name === 'SessionEnd') {
+        const cwd = typeof value.cwd === 'string' ? value.cwd : process.cwd();
         try {
-            await automaticSessionEnd('codex', value.session_id, value.cwd, env);
+            await automaticSessionEnd('codex', value.session_id, cwd, env);
         }
         catch { /* end remains bounded */ }
         return '';

package/dist/decisions.d.ts

@@ -1,5 +1,6 @@
 import { type ActivitiesOptions, type Act, type StoredAct, type SquareState, type Reach, type HardCap } from './model.js';
 import { peerPublicActs, peerRoomChanges } from './activity-feed.js';
+import { type Perception } from './square-core.js';
 export interface UnreadActivitySummary {
     name: string;
     count: number;
@@ -11,6 +12,7 @@ export interface UnreadActivityPreview {
     act: Extract<StoredAct, {
         kind: 'say';
     }>;
+    perception: Perception;
 }
 export declare function resolveKnownName(squareState: SquareState, name: string): string;
 export interface DecideJoinResult {
@@ -20,7 +22,16 @@ export interface DecideJoinResult {
         kind: 'join';
     }>;
 }
+export interface DecideImplicitJoinResult {
+    joinedName: string;
+    state: 'joined' | 'active' | 'done';
+    joinAct?: Extract<Act, {
+        kind: 'join';
+    }>;
+}
 export declare function decideJoin(squareState: SquareState, name: string, now: number): DecideJoinResult;
+/** Automatic presence may enter only once; an explicit join remains the re-entry path. */
+export declare function decideImplicitJoin(squareState: SquareState, name: string, now: number): DecideImplicitJoinResult;
 export type ActDecision = {
     type: 'sent';
     act: Act;
@@ -57,6 +68,13 @@ export declare function decideAct(squareState: SquareState, input: {
 export declare function coreDone(squareState: SquareState, name: string, body: string, now: number): Extract<Act, {
     kind: 'done';
 }>;
+export declare function coreListen(squareState: SquareState, actor: string, target: string, now: number): Extract<Act, {
+    kind: 'listen';
+}> | undefined;
+export declare function coreIgnore(squareState: SquareState, actor: string, target: string, now: number): Extract<Act, {
+    kind: 'ignore';
+}> | undefined;
+export declare function coreListening(squareState: SquareState, actor: string): readonly string[];
 export declare function coreHold(squareState: SquareState, actor: string, body: string, now: number): Extract<Act, {
     kind: 'hold';
 }>;
@@ -66,6 +84,7 @@ export declare function coreResume(squareState: SquareState, actor: string, now:
 export interface ParticipantStatus {
     name: string;
     state: 'active' | 'done' | 'not joined';
+    listening: readonly string[];
     activityCount: number;
     lastActiveAt: number | undefined;
     presence: CorePresenceState;

package/dist/decisions.js

@@ -1,9 +1,9 @@
 import { SquareError, sameName, validateName, } from './model.js';
 import { participantIdentity } from './participant-identity.js';
-import { UNREAD_BLOCK_GRACE_MS, actId, actStableIndex, foldedState, freshWatchLease, getReadState, publicActs, readCursor, resolveRosterName, rosterNames, matchesMentionTarget, THROTTLE_WINDOW_MS, } from './runtime.js';
+import { UNREAD_BLOCK_GRACE_MS, actId, actStableIndex, foldedState, freshWatchLease, publicActs, readCursor, resolveRosterName, rosterNames, THROTTLE_WINDOW_MS, } from './runtime.js';
 import { actDelta, peerPublicActs, peerRoomChanges } from './activity-feed.js';
-import { extractMentions, formatActivityId, validate } from './square-core.js';
-import { deriveDeliveryModel } from './delivery.js';
+import { formatActivityId, isListening, listeningTo, validate } from './square-core.js';
+import { deriveDeliveryModel, perceiveActivity } from './delivery.js';
 import { compileSearchPattern } from './search.js';
 export function resolveKnownName(squareState, name) {
     validateName(name);
@@ -32,6 +32,21 @@ export function decideJoin(squareState, name, now) {
         joinAct: { kind: 'join', actor: joinedName, at: now },
     };
 }
+/** Automatic presence may enter only once; an explicit join remains the re-entry path. */
+export function decideImplicitJoin(squareState, name, now) {
+    validateName(name);
+    const knownName = resolveRosterName(squareState, name);
+    const joinedName = knownName ?? name;
+    if (knownName !== undefined) {
+        const current = participantState(foldedState(squareState), knownName);
+        return { joinedName, state: current?.joined === true ? 'active' : 'done' };
+    }
+    return {
+        joinedName,
+        state: 'joined',
+        joinAct: { kind: 'join', actor: joinedName, at: now },
+    };
+}
 function resolveStandingName(squareState, requestedName) {
     validateName(requestedName);
     const name = resolveRosterName(squareState, requestedName);
@@ -65,10 +80,6 @@ export function decideAct(squareState, input) {
         }
     }
     const state = foldedState(squareState);
-    if (reach !== 'bell'
-        && extractMentions(body).length === 0) {
-        throw new SquareError('invalid_args', 'express requires an @mention unless using --bell');
-    }
     const current = participantState(state, name);
     const result = validate(state, {
         kind: 'say', actor: name, at: now, body,
@@ -108,7 +119,7 @@ export function decideAct(squareState, input) {
             latestAt: currentSummary === undefined ? item.at : Math.max(currentSummary.latestAt, item.at),
             previews: [
                 ...(currentSummary?.previews ?? []),
-                { number: sayCountByActor.get(actorKey) ?? 1, act: item },
+                { number: sayCountByActor.get(actorKey) ?? 1, act: item, perception: perceiveActivity(squareState, item, name) },
             ].slice(-UNREAD_PREVIEW_LIMIT),
         });
     }
@@ -147,6 +158,26 @@ export function coreDone(squareState, name, body, now) {
     requireStanding(squareState, act);
     return act;
 }
+export function coreListen(squareState, actor, target, now) {
+    const resolvedActor = resolveStandingName(squareState, actor);
+    validateName(target);
+    const state = foldedState(squareState);
+    const act = { kind: 'listen', actor: resolvedActor, target, at: now };
+    requireStanding(squareState, act);
+    return isListening(state, resolvedActor, target) ? undefined : act;
+}
+export function coreIgnore(squareState, actor, target, now) {
+    const resolvedActor = resolveStandingName(squareState, actor);
+    validateName(target);
+    const state = foldedState(squareState);
+    const act = { kind: 'ignore', actor: resolvedActor, target, at: now };
+    requireStanding(squareState, act);
+    return isListening(state, resolvedActor, target) ? act : undefined;
+}
+export function coreListening(squareState, actor) {
+    const resolvedActor = resolveStandingName(squareState, actor);
+    return listeningTo(foldedState(squareState), resolvedActor);
+}
 export function coreHold(squareState, actor, body, now) {
     const resolvedName = resolveStandingName(squareState, actor);
     const act = { kind: 'hold', actor: resolvedName, at: now, body: body.replace(/\r\n/g, '\n').trim() };
@@ -162,11 +193,11 @@ export function coreResume(squareState, actor, now) {
 function presenceFor(squareState, snapshot, name, now) {
     if (snapshot?.done)
         return { state: 'done', lastAt: snapshot.lastActiveAt };
-    const cursor = getReadState(squareState, name);
+    const cursorAt = squareState.acts.findLast((act) => act.index <= readCursor(squareState, name))?.at;
     const lease = freshWatchLease(squareState, name, now);
     if (lease !== undefined)
-        return { state: 'watching', lastAt: cursor?.updatedAt ?? lease.heartbeatAt };
-    const lastAt = cursor?.updatedAt ?? (snapshot?.joined ? snapshot.lastActiveAt : undefined);
+        return { state: 'watching', lastAt: cursorAt ?? lease.heartbeatAt };
+    const lastAt = cursorAt ?? (snapshot?.joined ? snapshot.lastActiveAt : undefined);
     return lastAt === undefined
         ? { state: 'never-joined', lastAt: undefined }
         : { state: 'active', lastAt };
@@ -190,6 +221,7 @@ function buildParticipantStatuses(squareState, now, state = foldedState(squareSt
         return {
             name: participant,
             state: participantStatus,
+            listening: listeningTo(state, participant),
             activityCount: snapshot?.activityCount ?? 0,
             lastActiveAt: snapshot?.lastActiveAt,
             presence: presence.state,
@@ -249,7 +281,8 @@ export function coreActivities(squareState, opts) {
         acts = acts.filter((act) => act.at > opts.after);
     if (opts.mention != null) {
         const mention = resolveKnownName(squareState, opts.mention);
-        acts = acts.filter((act) => act.kind === 'say' && (act.reach === 'bell' || matchesMentionTarget(act, mention)));
+        const delivery = deriveDeliveryModel(squareState);
+        acts = acts.filter((act) => act.kind === 'say' && delivery.plan(act).some((item) => sameName(item.recipient, mention)));
     }
     if (opts.pending) {
         if (viewer === undefined)

package/dist/delivery.d.ts

@@ -1,4 +1,5 @@
-import { type DeliveryReceipt, type DirectedNotificationRoute, type SquareState, type SquareRuntimeState, type StoredAct, type WatchLease, type WatchLeaseFilter, type WakeRouteKind, type Reach } from './model.js';
+import { type DirectedNotificationRoute, type SquareState, type StoredAct, type WatchLease, type WatchLeaseFilter, type WakeRouteKind, type Reach } from './model.js';
+import { type Perception } from './square-core.js';
 export type { DirectedNotificationRoute } from './model.js';
 export type SayItem = StoredAct & {
     kind: 'say';
@@ -28,6 +29,12 @@ export type WakeDispatchResult = {
     signature: string;
     message: string;
     diagnostic?: unknown;
+} | {
+    outcome: 'unavailable';
+    signature: string;
+    message: string;
+    diagnostic?: unknown;
+    retainRoute?: boolean;
 } | {
     outcome: 'cancelled';
 };
@@ -39,43 +46,29 @@ export interface RoutedNotification {
     actor: string;
     body: string;
     route: DirectedNotificationRoute;
+    recipient?: string;
 }
 export interface CatchFilterShape {
     actor: string;
     body: string;
     reach?: Reach;
+    recipients?: readonly string[];
 }
 export interface DeliveryModel {
     plan(item: StoredAct): PlannedNotification[];
     pendingFor(recipient: string): PlannedNotification[];
 }
-/** Delivery receipts are the only durable acknowledgement of directed attention. */
-export declare function deliveryReceipt(squareState: SquareState, name: string, actOrIndex: StoredAct | number): DeliveryReceipt | undefined;
-export declare function deliveryReceiptFromRuntime(runtime: SquareRuntimeState, recipient: string, actOrIndex: StoredAct | number): DeliveryReceipt | undefined;
-export declare function isDeliveryDelivered(squareState: SquareState, name: string, actOrIndex: StoredAct | number): boolean;
-export declare function recordDeliveredDelivery(squareState: SquareState, name: string, actOrIndex: StoredAct | number, receipt: Omit<DeliveryReceipt, 'status'>): boolean;
-export declare function recordDeliveredRuntime(runtime: SquareRuntimeState, recipient: string, actOrIndex: StoredAct | number, receipt: Omit<DeliveryReceipt, 'status'>): boolean;
-export declare function markDeliveredDelivery(squareState: SquareState, name: string, actOrIndex: StoredAct | number, at?: number): boolean;
+export declare function isActivitySeen(squareState: SquareState, name: string, actOrIndex: StoredAct | number): boolean;
 /**
  * Derive delivery behavior once from the decoded Square state.
  * All consumers share these targets instead of reinterpreting artifact text or cursor state.
  */
 export declare function deriveDeliveryModel(squareState: SquareState): DeliveryModel;
 export declare function planActNotifications(squareState: SquareState, item: StoredAct): PlannedNotification[];
-/** Mark only the directed notifications selected by the canonical pending projection. */
-export declare function markDeliveredNotifications(squareState: SquareState, recipient: string, delivered: StoredAct[], at?: number): boolean;
+export declare function perceiveActivity(squareState: SquareState, item: StoredAct, viewer: string): Perception;
+/** Mark only the notifications selected by the canonical catch projection as fully seen. */
+export declare function markSeenNotifications(squareState: SquareState, recipient: string, delivered: StoredAct[], at?: number): boolean;
 /** Canonical say-activity filter shared by catch selection and hook ownership. */
 export declare function matchesCatchFilter(activity: CatchFilterShape, filter: WatchLeaseFilter): boolean;
 /** True only when the live catch's own filters would deliver this notification. */
 export declare function leaseOwnsNotification(lease: WatchLease, notification: RoutedNotification): boolean;
-export type SquareRoute = Readonly<unknown>;
-interface ParsedSquareRoute {
-    readonly v: 1;
-    readonly squarePath: string;
-    readonly name: string;
-}
-export declare function parseSquareRoute(value: unknown): ParsedSquareRoute;
-export declare function captureRoute(input: {
-    cwd: string;
-    env?: NodeJS.ProcessEnv;
-}): SquareRoute | null;