@astrosheep/square 0.4.4 → 0.4.6

package/dist/mcp.js

@@ -5,23 +5,20 @@ import { operationEnv } from './participant-identity.js';
 import { codexWakeAddress } from './codex-address.js';
 import { readClaudeMcpCall } from './claude-mcp-context.js';
 import { SQUARE_IDENTITY } from './identity.js';
-import { Square, createSquareResourceOwner } from './square-api.js';
+import { Square, discover, squareClock } from './square-api.js';
 import { harnessOwner } from './square-api.js';
 export function createSquareMcpServer(options) {
     const { owner: configuredOwner, wakeAddress, ...resourceOptions } = options;
     const baseEnv = { ...(resourceOptions.env ?? process.env) };
     const toolsEnabled = squareToolsEnabled(baseEnv);
-    const resources = createSquareResourceOwner();
     const invoke = createSquareToolRunner();
-    // Calls to the configured square borrow one server-owned connection.
-    const inFlight = new Set();
     const server = new McpServer({ name: 'square', version: SQUARE_IDENTITY.packageVersion }, {
         ...(toolsEnabled ? { instructions: SQUARE_TOOL_INSTRUCTIONS } : {}),
     });
     if (toolsEnabled)
         for (const tool of SQUARE_TOOLS) {
             server.registerTool(tool.name, { description: tool.description, inputSchema: tool.inputSchema }, (args, extra) => {
-                const call = invoke(tool, args, { signal: extra.signal }, async () => {
+                return invoke(tool, args, { signal: extra.signal }, async () => {
                     const threadId = extra._meta?.threadId;
                     const opencodeSessionId = extra._meta?.['ai.opencode/sessionID'];
                     // Claude's bundled plugin requires a per-call native hook association; startup identity is not a fallback.
@@ -51,38 +48,17 @@ export function createSquareMcpServer(options) {
                     return {
                         identity: { owner, wakeAddress: claude === undefined && typeof threadId === 'string' && threadId.trim()
                                 ? { ...codexWakeAddress(threadId, env), kind: 'codex-queue' } : callWake },
-                        open: (location, control) => Square.at({
-                            ...resourceOptions, env, cwd: claude?.cwd ?? resourceOptions.cwd,
-                            path: location ?? options.path,
-                            // Overrides and Claude calls own their connections.
-                            resources: location === undefined && claude === undefined ? resources : undefined,
-                        }, control),
+                        open: (location, control) => Square.at({ ...resourceOptions, env, cwd: claude?.cwd ?? resourceOptions.cwd, path: location }, control),
+                        discover: async (discovery, control) => ({
+                            result: await discover({ ...resourceOptions, env, cwd: claude?.cwd ?? resourceOptions.cwd }, discovery, control),
+                            now: squareClock(env, resourceOptions.clock)(),
+                        }),
                     };
-                }, options.path).then(({ text, isError }) => ({
+                }).then(({ text, isError }) => ({
                     ...(isError ? { isError } : {}), content: [{ type: 'text', text }],
                 }));
-                inFlight.add(call);
-                return call.finally(() => { inFlight.delete(call); });
             });
         }
-    const close = server.close.bind(server);
-    // One idempotent shutdown for both close paths: an explicit server.close() and a
-    // transport-initiated disconnect, where the SDK protocol fires onclose by itself.
-    let draining;
-    const drain = () => draining ??= (async () => {
-        // The SDK aborts in-flight request signals before onclose/close returns; wait for
-        // those handlers to release the shared connection (their cleanup writes included).
-        await Promise.allSettled([...inFlight]);
-        await resources.close();
-    })();
-    server.close = async () => { await close(); await drain(); };
-    const priorOnclose = server.server.onclose;
-    server.server.onclose = () => {
-        // onclose is synchronous, so the disconnect path starts the drain without awaiting it;
-        // the handler's own catch keeps an unexpected close failure from crashing the process.
-        void drain().catch(() => undefined);
-        priorOnclose?.();
-    };
     return server;
 }
 export async function runSquareMcpStdio(options) {

package/dist/neutral.d.ts

@@ -9,7 +9,7 @@ export interface SquareErrorFacts {
     activityUnsent?: true;
     /** Refusal reason, including absent participants, conflicting reach, and inaccessible activities. */
     reason?: 'never_joined' | 'not_standing' | 'bell_mention_conflict' | 'not_addressed' | 'invalid_reply' | 'invalid_done_body' | 'needs_seat';
-    /** The activity id a `catch --id` refusal named. */
+    /** The activity id a `perceive --id` refusal named. */
     activityId?: string;
     /** Requested recipient spellings, without parsing presentation copy. */
     targets?: readonly string[];
@@ -18,7 +18,7 @@ export interface SquareErrorFacts {
     pending?: number;
     retryAfterMs?: number;
 }
-export interface CatchWaitStart {
+export interface PerceiveWaitStart {
     readonly idleMs: number;
     readonly replacementRequested: boolean;
     readonly replaced: boolean;
@@ -28,15 +28,15 @@ export type OperationProgress = {
     readonly reason: 'throttled';
     readonly delayMs?: number;
 } | ({
-    readonly kind: 'catch-started';
+    readonly kind: 'perceive-started';
     readonly participant: string;
-} & CatchWaitStart);
+} & PerceiveWaitStart);
 export interface OperationControl {
     readonly signal?: AbortSignal;
     readonly onProgress?: (progress: OperationProgress) => void;
 }
 export interface OperationFailureDetail {
-    readonly operation: 'express' | 'join' | 'catch' | 'history' | 'other';
+    readonly operation: 'express' | 'join' | 'perceive' | 'history' | 'other';
     readonly subject?: 'caller' | 'filter' | 'recipient';
     readonly participant?: string;
     readonly expressEffect?: 'unsent' | 'landed' | 'unknown';

package/dist/notifications.js

@@ -1,17 +1,23 @@
 import { createDefaultDeliveryTransports } from './wake-transports.js';
 export { createDefaultDeliveryTransports } from './wake-transports.js';
+function deliveryWaitMs(env = process.env) {
+    const configured = Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000);
+    return Number.isSafeInteger(configured) && configured > 0 ? configured : 5000;
+}
 /** Best-effort dispatch for currently eligible cards, including cards restored by release. */
 export async function dispatchEligibleCards(ledger, owner, options = {}) {
-    const session = await ledger.session(owner);
+    options = { ...options, signal: options.signal ?? AbortSignal.timeout(deliveryWaitMs(options.env)) };
+    const session = await ledger.session(owner, options.signal);
     if (!session || session.state !== 'attached' || options.signal?.aborted)
         return;
-    const pending = await ledger.pending(owner, { generation: session.generation });
+    const pending = await ledger.pending(owner, { generation: session.generation }, options.signal);
     for (const card of pending)
         await dispatchPostedCard(ledger, owner, card.key, options.track ?? (() => undefined), options.env, options.signal, options.transports);
 }
 /** Post, then best-effort dispatch without consulting producer storage. */
 export async function postAndDispatch(ledger, input, options = {}) {
-    const result = await ledger.post(input);
+    options = { ...options, signal: options.signal ?? AbortSignal.timeout(deliveryWaitMs(options.env)) };
+    const result = await ledger.post(input, options.signal);
     if (result.status === 'posted' || result.status === 'duplicate') {
         try {
             await dispatchEligibleCards(ledger, input.owner, options);
@@ -24,12 +30,12 @@ export async function postAndDispatch(ledger, input, options = {}) {
 export async function dispatchPostedCard(ledger, owner, key, track, env = process.env, signal, suppliedTransports) {
     if (signal?.aborted)
         return;
-    const session = await ledger.session(owner);
+    const timeoutMs = deliveryWaitMs(env);
+    signal ??= AbortSignal.timeout(timeoutMs);
+    const session = await ledger.session(owner, signal);
     if (!session || session.state !== 'attached')
         return;
     const transports = suppliedTransports ?? await createDefaultDeliveryTransports(env);
-    const configured = Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000);
-    const timeoutMs = Number.isSafeInteger(configured) && configured > 0 ? configured : 5000;
     for (const route of session.routes) {
         // Claude and Codex custody belongs to their native receivers, including for
         // callers that supply transports explicitly to the producer API.

package/dist/operation-presentation.d.ts

@@ -1,4 +1,9 @@
-import type { CatchOptions, CatchResult, ExpressResult, HistoryQuery, HistoryResult, JoinResult, LifecycleResult, ListenerChangeResult, ListeningResult, OperationFailureDetail, ParticipantsResult, StatusResult } from './square-facade.js';
+import type { PerceiveOptions, PerceiveResult, ExpressResult, HistoryQuery, HistoryResult, JoinResult, LifecycleResult, ListenerChangeResult, ListeningResult, OperationFailureDetail, ParticipantsResult, StatusResult, DiscoveryResult } from './square-facade.js';
+export declare function renderSquareList(data: DiscoveryResult, projection: {
+    now: number;
+    depth: number;
+    limit: number;
+}): string;
 export declare const PARTICIPANTS_DEFAULT_LIMIT = 20;
 export declare const PARTICIPANTS_MAX_LIMIT = 100;
 /** A join receipt whose participant is already reduced to its serializable name. */
@@ -9,8 +14,8 @@ export type JoinPresentation = Omit<JoinResult, 'participant'> & {
 };
 export declare function renderJoinResult(data: JoinPresentation, owner?: string): string | undefined;
 export declare function renderExpression(squarePath: string, data: ExpressResult, owner?: string): string | undefined;
-/** Render settled catch facts; no selection, terminal decisions, receipts or wait machinery. */
-export declare function renderCatchOutcome(squarePath: string, data: CatchResult, options?: CatchOptions, owner?: string): {
+/** Render settled perceive facts; no selection, terminal decisions, receipts or wait machinery. */
+export declare function renderPerceiveOutcome(squarePath: string, data: PerceiveResult, options?: PerceiveOptions, owner?: string): {
     stdout: string;
     exitCode: number;
 };

package/dist/operation-presentation.js

@@ -2,9 +2,47 @@
 // render through these functions, so a person sees the same square either way.
 import { sameName } from './model.js';
 import { formatActivityId } from './square-core.js';
-import { commandPrefix, joinRecoveryCommand, participantCommandPrefix, participantIdentity, participantsRecoveryCommand, quoteShell, renderAmbientEvent, renderAmbientEventFacts, renderEventCli, renderGrepActivitiesView, renderPresenceAnchor, renderWatchAlreadyActive, renderWatchReplaced, renderWatchStatus, takeoverRecoveryLines, withPathOutput, } from './presentation.js';
+import { commandPrefix, joinRecoveryCommand, participantCommandPrefix, participantIdentity, participantsRecoveryCommand, quoteShell, renderAmbientEvent, renderAmbientEventFacts, renderEventCli, renderGrepActivitiesView, renderPresenceAnchor, renderWatchAlreadyActive, renderWatchReplaced, renderWatchStatus, takeoverRecoveryLines, withPathOutput, truncateChars, } from './presentation.js';
 import { formatRelativeTime, formatTimestamp } from './time.js';
 import { style } from './tty-style.js';
+function listDisplay(value) {
+    const truncated = truncateChars(value, 159);
+    return truncated.remaining === 0 ? truncated.text : `${truncated.text}…`;
+}
+export function renderSquareList(data, projection) {
+    const { items, stopped, remaining, next } = data;
+    if (data.total === 0) {
+        return ['(no squares found)', ...(stopped ? [style('dim', '○ the walk stopped early — deeper squares may still be hiding')] : [])].join('\n') + '\n';
+    }
+    const lines = ['squares'];
+    for (const item of items) {
+        const glyph = item.activities > 0 ? '●' : style('dim', '○');
+        lines.push(`${glyph} ${listDisplay(item.path)}${style('dim', ` · ${formatRelativeTime(item.lastActiveAt, projection.now)} · ${item.participants.length} in the square · ${item.activities} ${item.activities === 1 ? 'activity' : 'activities'}`)}`);
+        const context = item.context.slice(0, 2);
+        if (context.length === 0)
+            lines.push(`  ${style('dim', 'context')} · (none)`);
+        else {
+            context.forEach((line, index) => lines.push(`  ${index === 0 ? style('dim', 'context') : '       '} · ${listDisplay(line)}`));
+            const hidden = item.context.length - context.length;
+            if (hidden > 0)
+                lines.push(style('dim', `          · … ${hidden} more ${hidden === 1 ? 'line' : 'lines'}`));
+        }
+        const participants = item.participants.slice(0, 3);
+        const hidden = item.participants.length - participants.length;
+        const names = participants.length === 0 ? 'nobody' : participants.map((name) => participantIdentity(listDisplay(name))).join(' · ');
+        lines.push(`  ${style('dim', 'participants')} · ${names}${hidden > 0 ? style('dim', ` · … ${hidden} more`) : ''}`);
+        if (item.joined?.length)
+            lines.push(`  ${style('dim', 'joined')} · ${item.joined.map(seat => `${participantIdentity(listDisplay(seat.name))}${seat.pending > 0 ? style('dim', ` (${seat.pending} waiting)`) : ''}`).join(' · ')}`);
+    }
+    if (remaining > 0) {
+        lines.push(style('dim', stopped ? '  … more squares' : `  … ${remaining} more ${remaining === 1 ? 'square' : 'squares'}`));
+        if (next !== undefined)
+            lines.push(`square list --depth ${projection.depth} --limit ${projection.limit} --after ${quoteShell(next)}`);
+    }
+    if (stopped)
+        lines.push(style('dim', '○ the walk stopped early — deeper squares may still be hiding'));
+    return lines.join('\n') + '\n';
+}
 export const PARTICIPANTS_DEFAULT_LIMIT = 20;
 export const PARTICIPANTS_MAX_LIMIT = 100;
 const STATUS_PARTICIPANT_PREVIEW_LIMIT = 10;
@@ -18,8 +56,8 @@ export function renderJoinResult(data, owner) {
         now: after.now, preview: 200, perception: event.perception,
     })).filter(Boolean).join('\n\n');
     const fallback = after.deliveryAvailable ? ['', '· when someone calls you, you’ll hear them here'] : [
-        '', `${participantCommandPrefix(after.location, name, owner)} catch --idle 30m`,
-        '  · stay within earshot — keep this catch open for new activity',
+        '', `${participantCommandPrefix(after.location, name, owner)} perceive --idle 30m`,
+        '  · stay within earshot — keep this perceive open for new activity',
     ];
     const entryLine = data.kind === 'joined' ? '● you stepped into the square'
         : data.kind === 'reconnected' ? '● you are already in the square'
@@ -49,7 +87,7 @@ export function renderExpression(squarePath, data, owner) {
         'Unread context · preview only, not consumed',
         ...context.activities.map(item => `· ${participantIdentity(item.actor)} · ${item.id}\n  ${item.preview}${item.truncated ? '… (truncated)' : ''}`),
         ...(context.remaining === 0 ? [] : [`· ${context.remaining} more unread activities`]),
-        `${participantCommandPrefix(projection.location, name, owner)} catch`,
+        `${participantCommandPrefix(projection.location, name, owner)} perceive`,
     ].join('\n');
     const ownCount = projection.ownActivityCount;
     const capCount = projection.hardCap === null ? '' : ` · ${ownCount}/${projection.hardCap}`;
@@ -73,10 +111,10 @@ function continuationCommand(squarePath, name, options, owner) {
         args.push('--mention');
     if (options.limit !== undefined)
         args.push('--limit', String(options.limit));
-    return `${participantCommandPrefix(squarePath, name, owner)} catch ${args.join(' ')}`;
+    return `${participantCommandPrefix(squarePath, name, owner)} perceive ${args.join(' ')}`;
 }
-/** Render settled catch facts; no selection, terminal decisions, receipts or wait machinery. */
-export function renderCatchOutcome(squarePath, data, options = {}, owner) {
+/** Render settled perceive facts; no selection, terminal decisions, receipts or wait machinery. */
+export function renderPerceiveOutcome(squarePath, data, options = {}, owner) {
     const projection = data.observation;
     if (projection === undefined)
         return { stdout: '', exitCode: 0 };
@@ -86,7 +124,7 @@ export function renderCatchOutcome(squarePath, data, options = {}, owner) {
     const header = { participantCount: projection.standingCount };
     const statusOptions = {
         squarePath: location, name, owner, presence: projection.presence,
-        showCatchHint: !projection.deliveryAvailable,
+        showPerceiveHint: !projection.deliveryAvailable,
         ownActivityCount: projection.ownActivityCount, hardCap: projection.hardCap,
     };
     if (stop === 'already-active' || stop === 'replaced') {
@@ -106,7 +144,7 @@ export function renderCatchOutcome(squarePath, data, options = {}, owner) {
         ...(stop === 'idle' && options.idle !== undefined ? { idleMs: options.idle } : {}),
     });
     const fallback = stop === undefined && !projection.deliveryAvailable && data.remaining === 0
-        ? `${participantCommandPrefix(location, name, owner)} catch --idle 30m\n  stay available for new activity` : '';
+        ? `${participantCommandPrefix(location, name, owner)} perceive --idle 30m\n  stay available for new activity` : '';
     const hint = data.hint === undefined ? '' : style('dim', `· ${data.hint}`);
     return {
         stdout: withPathOutput(location, [terminal, rendered, hint, remaining, fallback].filter(Boolean).join('\n\n'), header),
@@ -187,7 +225,7 @@ export function renderParticipantsResult(squarePath, data, limit = PARTICIPANTS_
     const participants = data.participants;
     const lines = participants.slice(0, limit).map((participant) => {
         const glyph = participant.presence === 'done' ? '○' : participant.presence === 'watching' ? '◎' : participant.activityCount > 0 && projection.classificationByName[participant.name] === 'here' ? '●' : '○';
-        const state = participant.presence === 'watching' ? 'catching' : participant.presence === 'never-joined' ? 'not joined' : participant.presence;
+        const state = participant.presence === 'watching' ? 'perceiving' : participant.presence === 'never-joined' ? 'not joined' : participant.presence;
         const last = participant.lastActiveAt === undefined ? '—' : formatRelativeTime(participant.lastActiveAt, now);
         return `  ${glyph} ${participant.name}${style('dim', ` · ${state} · ${participant.activityCount} ${participant.activityCount === 1 ? 'activity' : 'activities'} · ${last}`)}`;
     });
@@ -223,7 +261,7 @@ export function renderStatusResult(squarePath, data) {
                 ? '◎'
                 : participant.activityCount > 0 ? '●' : '○';
             const summary = participant.presence === 'watching'
-                ? 'is nearby · catching'
+                ? 'is nearby · perceiving'
                 : participant.activityCount > 0
                     ? `is nearby · ${formatRelativeTime(participant.lastActiveAt ?? data.now, data.now)}`
                     : `is nearby · quiet · ${participant.lastActiveAt === undefined ? 'just now' : formatRelativeTime(participant.lastActiveAt, data.now)}`;
@@ -234,7 +272,7 @@ export function renderStatusResult(squarePath, data) {
                     ? `${participant.pendingMentionCount} ${participant.pendingMentionCount === 1 ? 'mention' : 'mentions'} waiting`
                     : participant.unreadActivityCount > 0
                         ? `${participant.unreadActivityCount} change${participant.unreadActivityCount === 1 ? '' : 's'} waiting`
-                        : 'caught up';
+                        : 'up to date';
             return `  ${glyph} ${participantIdentity(participant.name)}${style('dim', ` ${summary}${attention === '' ? '' : ` · ${attention}`}`)}`;
         }));
         people.push(...away.slice(0, STATUS_PARTICIPANT_PREVIEW_LIMIT).map(participant => `  ○ ${participantIdentity(participant.name)}${style('dim', ' · away')}`));

package/dist/packages/agent-delivery/src/file-lock.js

@@ -12,7 +12,10 @@ export class FileLockError extends Error {
     }
 }
 function isBusy(error) {
-    return error instanceof Error && /database is locked|SQLITE_BUSY/i.test(error.message);
+    const code = error?.code;
+    return typeof code === 'string' && /^SQLITE_BUSY(?:_|$)/.test(code)
+        || typeof error?.errcode === 'number' && (error.errcode & 0xff) === 5
+        || error instanceof Error && /database is locked|database is busy|SQLITE_BUSY/i.test(error.message);
 }
 function isNotADatabase(error) {
     return error instanceof Error && /not a database|file is not a database/i.test(error.message);

package/dist/perceive-decisions.d.ts

@@ -0,0 +1,28 @@
+import { type HydratedAct } from './model.js';
+import type { ActivityIndex, DirectedFilter, SquareRead, SquareWrite } from './ports.js';
+import type { PerceiveOptions, PerceiveReason, PerceivedActivity } from './square-facade.js';
+export interface PerceiveSelection {
+    readonly participant: string;
+    readonly activities: readonly PerceivedActivity[];
+    readonly remaining: number;
+    readonly standingCount: number;
+    readonly deliveryAvailable: boolean;
+    readonly now: number;
+    readonly ownActivityCount: number;
+    readonly hardCap: number | null;
+    readonly terminalStatus: Extract<PerceiveReason, 'capped' | 'quorum'> | undefined;
+    readonly hint?: string;
+}
+/** Capture a selected page (or an empty completion) without opening another resource. */
+export declare function observePerceiveSelection(facts: SquareRead, participant: string, activities: readonly HydratedAct[], filter: DirectedFilter, at: number, remaining?: number): PerceiveSelection;
+export declare const PERCEIVE_DEFAULT_LIMIT = 10;
+export declare const PERCEIVE_MAX_LIMIT = 100;
+export declare function perceiveLimit(value: number | undefined): number;
+/** Select non-ID perceive coordinates without hydrating bodies or recording receipts. */
+export declare function selectPerceivePage(facts: SquareRead, requestedName: string, options: PerceiveOptions): {
+    readonly participant: string;
+    readonly indexes: readonly ActivityIndex[];
+    readonly filter: DirectedFilter;
+};
+/** Selection, receipts and resulting cursor belong to one artifact write transaction. */
+export declare function decidePerceive(facts: SquareWrite, requestedName: string, options: PerceiveOptions, at: number): PerceiveSelection;

package/dist/{catch-decisions.js → perceive-decisions.js}

@@ -3,13 +3,13 @@ import { terminalStatusFor } from './runtime.js';
 import { SquareError } from './model.js';
 import { resolveKnownName } from './decisions.js';
 import { toPerceivedActivity } from './views.js';
-import { catchHint } from './hints.js';
+import { perceiveHint } from './hints.js';
 import { consumeReceived, ReceiveError, selectReceivedHeads } from './receive.js';
 import { squareReceiveRead } from './square-receive.js';
 /** Capture a selected page (or an empty completion) without opening another resource. */
-export function observeCatchSelection(facts, participant, activities, filter, at, remaining) {
+export function observePerceiveSelection(facts, participant, activities, filter, at, remaining) {
     if (typeof at !== 'number' || !Number.isFinite(at))
-        throw new SquareError('invalid_args', 'Catch time must be a finite number.');
+        throw new SquareError('invalid_args', 'Perceive time must be a finite number.');
     const counts = facts.participantCounts(), header = facts.header(), current = facts.participant(participant);
     return {
         participant, activities: activities.map(activity => toPerceivedActivity(facts, activity, participant)),
@@ -20,44 +20,44 @@ export function observeCatchSelection(facts, participant, activities, filter, at
         terminalStatus: terminalStatusFor(current, header.hardCap, counts),
     };
 }
-export const CATCH_DEFAULT_LIMIT = 10;
-export const CATCH_MAX_LIMIT = 100;
-export function catchLimit(value) {
-    const limit = value ?? CATCH_DEFAULT_LIMIT;
-    if (!Number.isSafeInteger(limit) || limit < 1 || limit > CATCH_MAX_LIMIT) {
-        throw new SquareError('invalid_args', `Catch limit must be a positive integer no greater than ${CATCH_MAX_LIMIT}.`);
+export const PERCEIVE_DEFAULT_LIMIT = 10;
+export const PERCEIVE_MAX_LIMIT = 100;
+export function perceiveLimit(value) {
+    const limit = value ?? PERCEIVE_DEFAULT_LIMIT;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > PERCEIVE_MAX_LIMIT) {
+        throw new SquareError('invalid_args', `Perceive limit must be a positive integer no greater than ${PERCEIVE_MAX_LIMIT}.`);
     }
     return limit;
 }
-function catchPageSelection(facts, requestedName, options) {
+function perceivePageSelection(facts, requestedName, options) {
     const participant = resolveKnownName(facts, requestedName);
-    const limit = catchLimit(options.limit);
+    const limit = perceiveLimit(options.limit);
     const senders = options.from?.map(name => resolveKnownName(facts, name));
     const filter = { kinds: ['say'], unseenOnly: true, ...(senders === undefined ? {} : { senders }), ...(options.mention === true ? { attentionOnly: true } : {}) };
     return { participant, filter, selection: { kind: 'page', query: filter, limit } };
 }
-/** Select non-ID catch coordinates without hydrating bodies or recording receipts. */
-export function selectCatchPage(facts, requestedName, options) {
-    const { participant, filter, selection } = catchPageSelection(facts, requestedName, options);
+/** Select non-ID perceive coordinates without hydrating bodies or recording receipts. */
+export function selectPerceivePage(facts, requestedName, options) {
+    const { participant, filter, selection } = perceivePageSelection(facts, requestedName, options);
     return { participant, indexes: selectReceivedHeads(squareReceiveRead(facts), participant, selection).map(item => item.key), filter };
 }
 /** Selection, receipts and resulting cursor belong to one artifact write transaction. */
-export function decideCatch(facts, requestedName, options, at) {
+export function decidePerceive(facts, requestedName, options, at) {
     let viewer;
     let filter = { kinds: ['say'], unseenOnly: true };
     let selection;
     if (options.id !== undefined) {
         viewer = resolveKnownName(facts, requestedName);
-        catchLimit(options.limit);
+        perceiveLimit(options.limit);
         if (['idle', 'from', 'mention', 'limit'].some((key) => Object.hasOwn(options, key)))
-            throw new SquareError('invalid_args', 'Catch id cannot be combined with idle, from, mention or limit.');
+            throw new SquareError('invalid_args', 'Perceive id cannot be combined with idle, from, mention or limit.');
         const index = parseActivityId(options.id);
         if (index === undefined)
-            throw new SquareError('invalid_args', 'Invalid catch id: expected an activity id like act/12.');
+            throw new SquareError('invalid_args', 'Invalid perceive id: expected an activity id like act/12.');
         selection = { kind: 'exact', key: index, remainingQuery: filter };
     }
     else {
-        const page = catchPageSelection(facts, requestedName, options);
+        const page = perceivePageSelection(facts, requestedName, options);
         viewer = page.participant;
         filter = page.filter;
         selection = page.selection;
@@ -87,10 +87,10 @@ export function decideCatch(facts, requestedName, options, at) {
         });
     }
     const delivered = consumed.items.map(item => item.data);
-    const observed = observeCatchSelection(facts, viewer, delivered, filter, at, consumed.remaining);
-    // Receipts are the durable catch count: everything directed here minus what is still unseen.
-    const caught = facts.directedCount(viewer, { kinds: ['say'] }) - facts.directedCount(viewer, { kinds: ['say'], unseenOnly: true });
-    // An exact id catch is a targeted fetch and stays repeatable, so it carries no nudge.
-    const hint = options.id === undefined ? catchHint(caught - consumed.newlyConsumed, caught) : undefined;
+    const observed = observePerceiveSelection(facts, viewer, delivered, filter, at, consumed.remaining);
+    // Receipts are the durable perceive count: everything directed here minus what is still unseen.
+    const perceived = facts.directedCount(viewer, { kinds: ['say'] }) - facts.directedCount(viewer, { kinds: ['say'], unseenOnly: true });
+    // An exact id perceive is a targeted fetch and stays repeatable, so it carries no nudge.
+    const hint = options.id === undefined ? perceiveHint(perceived - consumed.newlyConsumed, perceived) : undefined;
     return hint === undefined ? observed : { ...observed, hint };
 }

package/dist/{catch-selection.d.ts → perceive-selection.d.ts}

@@ -1,6 +1,6 @@
 import { type Audience } from './square-core.js';
 /** Pure filter over settled audience facts; unread/directed eligibility and paging belong to callers. */
-export declare function matchesCatchSelection(actor: string, audience: Audience, filter: {
+export declare function matchesPerceiveSelection(actor: string, audience: Audience, filter: {
     readonly participants?: readonly string[];
     readonly mention?: string;
 }, replyAuthor?: string): boolean;
@@ -10,5 +10,5 @@ export interface RoutedNotification {
     readonly route: import('./model.js').DirectedNotificationRoute;
     readonly recipient: string;
 }
-/** A live catch owns every matching notification, independent of its page size. */
+/** A live perceive owns every matching notification, independent of its page size. */
 export declare function leaseOwnsNotification(lease: import('./model.js').WatchLease, notification: RoutedNotification): boolean;

package/dist/{catch-selection.js → perceive-selection.js}

@@ -1,7 +1,7 @@
 import { sameName } from './model.js';
 import { audienceIncludes } from './square-core.js';
 /** Pure filter over settled audience facts; unread/directed eligibility and paging belong to callers. */
-export function matchesCatchSelection(actor, audience, filter, replyAuthor) {
+export function matchesPerceiveSelection(actor, audience, filter, replyAuthor) {
     if (filter.participants !== undefined && !filter.participants.some((participant) => sameName(participant, actor))) {
         return false;
     }
@@ -12,8 +12,8 @@ export function matchesCatchSelection(actor, audience, filter, replyAuthor) {
     return audienceIncludes(audience, filter.mention)
         || (replyAuthor !== undefined && sameName(replyAuthor, filter.mention));
 }
-/** A live catch owns every matching notification, independent of its page size. */
+/** A live perceive owns every matching notification, independent of its page size. */
 export function leaseOwnsNotification(lease, notification) {
-    return matchesCatchSelection(notification.actor, notification.route === 'bell' ? { kind: 'bell' }
+    return matchesPerceiveSelection(notification.actor, notification.route === 'bell' ? { kind: 'bell' }
         : { kind: 'mentions', names: notification.route === 'mention' ? [notification.recipient] : [] }, lease.filter ?? {}, notification.route === 'reply' ? notification.recipient : undefined);
 }

package/dist/plugins/opencode/index.js

@@ -48,8 +48,8 @@ export default {
             return async () => { };
         }
         const env = { ...process.env };
-        const discovery = await observeOpenCodeSessions(env);
         const lifetime = new AbortController();
+        const discovery = await observeOpenCodeSessions(env, lifetime.signal);
         const receivers = new Map(); // Operational handles only; presence owns membership.
         const interrupting = new Set();
         const cancellationFailed = new Set();
@@ -80,7 +80,7 @@ export default {
             return target;
         };
         const reconcile = async (activeSession) => {
-            const candidates = new Set(await listOpenCodeSessions(env));
+            const candidates = new Set(await listOpenCodeSessions(env, lifetime.signal));
             if (activeSession)
                 candidates.add(activeSession);
             for (const sessionId of candidates) {
@@ -93,7 +93,7 @@ export default {
                     const receiver = receivers.get(sessionId);
                     stop(sessionId);
                     if (receiver)
-                        await detachOpenCodeSession(sessionId, receiver.generation, env);
+                        await detachOpenCodeSession(sessionId, receiver.generation, env, lifetime.signal);
                     continue;
                 }
                 const existing = receivers.get(sessionId);
@@ -171,7 +171,7 @@ export default {
                         const receiver = receivers.get(sessionId);
                         stop(sessionId);
                         if (receiver)
-                            await detachOpenCodeSession(sessionId, receiver.generation, env);
+                            await detachOpenCodeSession(sessionId, receiver.generation, env, lifetime.signal);
                         await reconcile();
                     });
                 else if (event.type === 'session.execution.interrupted' && event.data.reason === 'user') {

package/dist/plugins/opencode-shared/delivery.d.ts

@@ -7,17 +7,17 @@ export interface OpenCodeContextMessage {
         readonly text?: string;
     }[];
 }
-export declare function listOpenCodeSessions(env: NodeJS.ProcessEnv): Promise<readonly string[]>;
+export declare function listOpenCodeSessions(env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<readonly string[]>;
 /** The file observer is a hint; callers must always reread the ledger after an edge. */
-export declare function observeOpenCodeSessions(env: NodeJS.ProcessEnv): Promise<{
+export declare function observeOpenCodeSessions(env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<{
     observer: import("../../file-changes.js").VersionObserver<string>;
     close: () => Promise<void>;
 }>;
 export declare function publishOpenCodeAddress(sessionId: string, env: NodeJS.ProcessEnv, signal: AbortSignal): Promise<string | undefined>;
-export declare function currentOpenCodeGeneration(sessionId: string, env: NodeJS.ProcessEnv): Promise<string | undefined>;
-export declare function detachOpenCodeSession(sessionId: string, generation: string, env: NodeJS.ProcessEnv): Promise<void>;
-export declare function endOpenCodeSession(sessionId: string, generation: string, env: NodeJS.ProcessEnv): Promise<void>;
-export declare function cancelOpenCodeDeliveries(sessionId: string, generation: string, env: NodeJS.ProcessEnv): Promise<boolean>;
+export declare function currentOpenCodeGeneration(sessionId: string, env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<string | undefined>;
+export declare function detachOpenCodeSession(sessionId: string, generation: string, env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<void>;
+export declare function endOpenCodeSession(sessionId: string, generation: string, env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<void>;
+export declare function cancelOpenCodeDeliveries(sessionId: string, generation: string, env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<boolean>;
 /** Confirmation is observer-level: another host plugin may subsequently remove the message. */
 export declare function observeOpenCodeContext(sessionId: string, generation: string, messages: readonly OpenCodeContextMessage[], env: NodeJS.ProcessEnv, signal: AbortSignal): Promise<void>;
 export declare function receiveOpenCodePending(sessionId: string, generation: string, transport: DeliveryTransport, env: NodeJS.ProcessEnv, signal: AbortSignal): Promise<void>;