@astrosheep/square 0.3.96 → 0.3.97

package/dist/artifact.d.ts

@@ -34,7 +34,7 @@ export declare function writeSquareFile(location: string, state: SquareState, si
 /** Explicit test/export projection. Hot callers must use the typed port. */
 export declare function readSquareSnapshot(location: string, signal?: AbortSignal): Promise<SquareSnapshot>;
 export declare function readSquareRevision(location: string, signal?: AbortSignal): Promise<number>;
-export declare function observeSquareRevision(location: string): Promise<import('./file-changes.js').VersionObserver<number | null>>;
 export declare function readSquareDeliveryRevision(location: string, signal?: AbortSignal): Promise<number>;
+export declare function observeSquareRevision(location: string): Promise<import('./file-changes.js').VersionObserver<number | null>>;
 export declare function observeSquareDeliveryRevision(location: string): Promise<import('./file-changes.js').VersionObserver<number | null>>;
 export declare function diagnoseSquareFile(location: string): Promise<DiagnoseResult>;

package/dist/artifact.js

@@ -120,7 +120,7 @@ const readMethods = [
     'header', 'participant', 'roster', 'attention', 'incomingAttention',
     'activity', 'activityHeads', 'activities', 'activityCount', 'contextIndexes', 'sayOrdinals', 'recentSayTimes',
     'audience', 'directed', 'directedAt', 'directedCount', 'pendingAudience',
-    'receipt', 'receiptFacts', 'receiptAssignments', 'lease', 'participantCounts', 'seat', 'seatsForOwner',
+    'receipt', 'receiptFacts', 'lease', 'participantCounts', 'seat', 'seatsForOwner',
     'deliveryEvidence', 'deliveryByToken', 'cancelledThrough', 'deliveryDeferrals',
 ];
 const writeMethods = ['applyLanding', 'markSeen', 'putLease', 'removeLease', 'storeSeat', 'removeSeat', 'updateWakeAddress', 'reattachSeat', 'detachSeat', 'cancelThrough', 'claimDelivery', 'prepareDelivery', 'completeDelivery', 'observeNativeDelivery', 'putDeliveryDeferral', 'renewDeliveryDeferral', 'releaseDeliveryDeferral'];
@@ -404,26 +404,14 @@ export function readSquareSnapshot(location, signal) {
 export function readSquareRevision(location, signal) {
     return inspectFile(location, db => createSqliteDriver(db).header().revision, signal);
 }
-export function observeSquareRevision(location) {
-    return observeFileVersion(location, 'square-revision', async (file, signal) => {
-        try {
-            return await readSquareRevision(file, signal);
-        }
-        catch (error) {
-            abort(signal);
-            if (error instanceof InternalSquareError && error.code === 'not_found')
-                return null;
-            throw error;
-        }
-    });
-}
 export function readSquareDeliveryRevision(location, signal) {
     return inspectFile(location, db => createSqliteDriver(db).header().deliveryRevision, signal);
 }
-export function observeSquareDeliveryRevision(location) {
-    return observeFileVersion(location, 'square-delivery-revision', async (file, signal) => {
+function observeRevision(location, revision) {
+    const read = revision === 'square-revision' ? readSquareRevision : readSquareDeliveryRevision;
+    return observeFileVersion(location, revision, async (file, signal) => {
         try {
-            return await readSquareDeliveryRevision(file, signal);
+            return await read(file, signal);
         }
         catch (error) {
             abort(signal);
@@ -433,6 +421,12 @@ export function observeSquareDeliveryRevision(location) {
         }
     });
 }
+export function observeSquareRevision(location) {
+    return observeRevision(location, 'square-revision');
+}
+export function observeSquareDeliveryRevision(location) {
+    return observeRevision(location, 'square-delivery-revision');
+}
 export async function diagnoseSquareFile(location) {
     try {
         return { problems: [], ...await inspectFile(await canonicalPath(location), inspectSqlite) };

package/dist/boundary-presentation.js

@@ -22,17 +22,15 @@ function renderBoundary(inbox) {
     const omission = (count) => `${count} more ${count === 1 ? 'activity' : 'activities'} not shown.`;
     for (const entry of queued) {
         const { membership, notification } = entry;
-        const block = [
-            renderAttentionPreview({
-                squarePath: membership.location,
-                actIndex: notification.actIndex,
-                recipient: membership.seat.participant,
-                actor: notification.actor,
-                route: notification.route,
-                body: notification.body,
-                delivery: notification.delivery,
-            }),
-        ].join('\n');
+        const block = renderAttentionPreview({
+            squarePath: membership.location,
+            actIndex: notification.actIndex,
+            recipient: membership.seat.participant,
+            actor: notification.actor,
+            route: notification.route,
+            body: notification.body,
+            delivery: notification.delivery,
+        });
         if (notification.delivery?.mode !== 'direct') {
             remainingAgora -= 1;
             const omittedAfter = omitted + remainingAgora;
@@ -47,7 +45,7 @@ function renderBoundary(inbox) {
         deliveries.push(notification.delivery);
         complete.push({
             membership,
-            actIndexes: [notification.actIndex],
+            actIndex: notification.actIndex,
             markSeen: !attentionBodyIsClipped(notification.body, notification.delivery),
         });
     }
@@ -76,12 +74,10 @@ async function presentPendingAtBoundaryUnlocked(identity, present, lookup = sess
                     artifact = createArtifactPort(location);
                     artifacts.set(location, artifact);
                 }
-                for (const index of entry.actIndexes) {
-                    const claim = await preparePendingPresentation({ artifact, location, participant: seat.participant,
-                        activity: index, seat, markSeen: entry.markSeen, signal });
-                    if (claim !== undefined)
-                        claims.push({ key: pendingKey(entry.membership, index), claim });
-                }
+                const claim = await preparePendingPresentation({ artifact, location, participant: seat.participant,
+                    activity: entry.actIndex, seat, markSeen: entry.markSeen, signal });
+                if (claim !== undefined)
+                    claims.push({ key: pendingKey(entry.membership, entry.actIndex), claim });
             }
         }
         catch (error) {
@@ -94,7 +90,7 @@ async function presentPendingAtBoundaryUnlocked(identity, present, lookup = sess
             const fresh = renderBoundary(pending.map(membership => ({ ...membership,
                 notifications: membership.notifications.filter(note => eligible.has(pendingKey(membership, note.actIndex))),
             })));
-            const included = new Set(fresh.complete.flatMap(entry => entry.actIndexes.map(index => pendingKey(entry.membership, index))));
+            const included = new Set(fresh.complete.map(entry => pendingKey(entry.membership, entry.actIndex)));
             return { payload: fresh.context, included: claims.filter(({ key }) => included.has(key)).map(({ claim }) => claim) };
         }, present, { signal, classifyError: () => 'failed' });
         if (report.observation.kind === 'threw')

package/dist/channel.d.ts

@@ -1,8 +1,8 @@
 import { type HarnessSessionChannel } from './participant-identity.js';
 import type { SquareResourceOwner, WakeTransportPort } from './ports.js';
-import type { ActivityId, ChannelSendInput, ChannelSendResult, DeliveryDeferral, HeldSeat, MetadataMatch, OperationControl, Owner, Participant, WakeAddress } from './square-facade.js';
+import type { ActivityId, ChannelSendInput, ChannelSendResult, DeliveryDeferral, HeldSeat, MetadataMatch, OperationControl, Owner, Participant, WakeAddress, PendingOptions, PendingResult, AckResult } from './square-facade.js';
 export { harnessOwner, decodeHarnessOwner, localUserOwner } from './owner.js';
-export type { ActivityDelivery, ActivityMetadata, ChannelTruncate } from './square-facade.js';
+export type { ActivityDelivery, ActivityMetadata, ChannelTruncate, PerceivedActivity, PendingOptions, PendingResult, AckResult } from './square-facade.js';
 export type { ActivityId, ChannelSendInput, ChannelSendResult, DeliveryDeferral, HeldSeat, MetadataMatch, OperationControl, Owner, WakeAddress, SquareResourceOwner, WakeTransportPort, HarnessSessionChannel };
 export interface ResolvedHarnessSession {
     readonly channel: HarnessSessionChannel;
@@ -61,6 +61,8 @@ export declare class ChannelEndpoint {
     constructor(channel: Channel, participant: Participant);
     get name(): string;
     get generation(): ActivityId;
+    pending(options?: PendingOptions, control?: OperationControl): Promise<PendingResult>;
+    ack(ids: readonly ActivityId[], control?: OperationControl): Promise<AckResult>;
     leave(control?: OperationControl): Promise<void>;
     deferDelivery(input: Readonly<{
         match: MetadataMatch;

package/dist/channel.js

@@ -70,6 +70,12 @@ export class ChannelEndpoint {
     }
     get name() { return this.participant.name; }
     get generation() { return this.participant.generation; }
+    pending(options, control) {
+        return this.participant.pending(options, control);
+    }
+    ack(ids, control) {
+        return this.participant.ack(ids, control);
+    }
     async leave(control) { await this.participant.done(undefined, {}, control); }
     deferDelivery(input, control) {
         return this.participant.deferDelivery(input, control);

package/dist/claude-delivery.js

@@ -12,12 +12,6 @@ const marker = /(?:^|\n)\[square-inbox:([a-zA-Z0-9-]+)\](?:\n|$)/g;
 export function nativeTokens(text) { return [...text.matchAll(marker)].map((match) => match[1]); }
 export function nativePayload(token, preview) { return `[square-inbox:${token}]\n${preview}\n[/square-inbox:${token}]`; }
 function nativeSupported(route) { return route.address.loaded === 'true' && !!route.address.endpoint; }
-function sameAddress(left, right) {
-    if (left === undefined)
-        return false;
-    const keys = Object.keys(left);
-    return keys.length === Object.keys(right).length && keys.every((key) => left[key] === right[key]);
-}
 function hashPayload(payload) { return createHash('sha256').update(payload).digest('hex'); }
 function previewFacts(facts, request) {
     const index = parseActivityId(request.activity);
@@ -80,8 +74,7 @@ function currentPayload(facts, request) {
     const seat = facts.seat(request.participant), evidence = facts.deliveryByToken(request.claimToken);
     if (seat === undefined || seat.attachment !== 'attached' || evidence === undefined || seat.generation !== evidence.generation
         || seat.generation !== request.seat.generation || seat.owner !== request.seat.owner
-        || evidence.activity !== request.activity || !['dispatching', 'unknown', 'accepted'].includes(evidence.outcome)
-        || seat.wakeAddress?.kind !== 'claude-native' || !sameAddress(seat.wakeAddress.address, request.route.address))
+        || evidence.activity !== request.activity || !['dispatching', 'unknown', 'accepted'].includes(evidence.outcome))
         return undefined;
     const native = previewFacts(facts, request);
     if (native === undefined)

package/dist/cli/observation-commands.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { once } from 'node:events';
 import { runClaudeMod } from '../claude-mod.js';
-import { runCodexHookAsync } from '../codex-hook.js';
+import { runCodexHook } from '../codex-hook.js';
 import { isSquareError } from '../model.js';
 import { commandPrefix, participantIdentity, truncateChars, withPathOutput, quoteShell, } from '../presentation.js';
 import { PARTICIPANTS_DEFAULT_LIMIT, PARTICIPANTS_MAX_LIMIT, renderHistoryResult, renderParticipantsResult, renderStatusResult, } from '../operation-presentation.js';
@@ -523,4 +523,4 @@ function hookCommand(runHook) {
     };
 }
 export const claudeModCommand = hookCommand(runClaudeMod);
-export const codexHookCommand = hookCommand(runCodexHookAsync);
+export const codexHookCommand = hookCommand(runCodexHook);

package/dist/codex-hook.d.ts

@@ -5,10 +5,8 @@ export interface CodexHookInput {
     session_id?: unknown;
     hook_event_name?: unknown;
     cwd?: unknown;
-    source?: unknown;
 }
 export type HookTrace = (line: string) => void;
 export declare const CODEX_HOOK_BUDGET_MS = 4500;
 export declare function codexHookResponse(input: CodexHookInput, lookup?: (identity: Owner, env?: NodeJS.ProcessEnv, signal?: AbortSignal) => Promise<PendingMembership[]> | PendingMembership[], env?: NodeJS.ProcessEnv, deliveryTransports?: WakeTransports, trace?: HookTrace): Promise<object | undefined>;
 export declare function runCodexHook(inputText: string, env?: NodeJS.ProcessEnv): Promise<string>;
-export declare const runCodexHookAsync: typeof runCodexHook;

package/dist/codex-hook.js

@@ -47,4 +47,3 @@ export async function runCodexHook(inputText, env = process.env) {
     const result = await codexHookResponse(input, sessionInbox, env);
     return result === undefined ? '' : `${JSON.stringify(result)}\n`;
 }
-export const runCodexHookAsync = runCodexHook;

package/dist/decisions.d.ts

@@ -7,12 +7,7 @@ type TimedAct<K extends Act['kind'] = Act['kind']> = Extract<Act, {
 };
 import type { ExpressResult, ParticipantSummary, UnreadActivitySummary } from './square-facade.js';
 export declare function resolveKnownName(facts: SquareRead, name: string): string;
-export interface DecideJoinResult {
-    joinedName: string;
-    addParticipant: boolean;
-    joinAct?: TimedAct<'join'>;
-}
-export declare function decideJoin(facts: SquareRead, name: string, now: number): DecideJoinResult;
+export declare function decideJoin(facts: SquareRead, name: string, now: number): TimedAct<'join'> | undefined;
 export type ActDecision = ({
     type: 'sent';
     act: TimedAct;
@@ -21,8 +16,6 @@ export type ActDecision = ({
     activitySummaries: UnreadActivitySummary[];
 } | {
     type: 'capped';
-    count: number;
-    hardCap: number;
 } | {
     type: 'throttled';
     delayMs: number;
@@ -45,9 +38,7 @@ export declare function decideAct(facts: SquareRead, input: {
 }): ActDecision;
 export declare function validateDoneBody(body: unknown): void;
 export declare function coreDone(facts: SquareRead, name: string, body: string, now: number): TimedAct<'done'>;
-export declare function coreListen(facts: SquareRead, actor: string, target: string, now: number): TimedAct<"listen" | "ignore" | "unlisten"> | undefined;
-export declare function coreIgnore(facts: SquareRead, actor: string, target: string, now: number): TimedAct<"listen" | "ignore" | "unlisten"> | undefined;
-export declare function coreUnlisten(facts: SquareRead, actor: string, target: string, now: number): TimedAct<"listen" | "ignore" | "unlisten"> | undefined;
+export declare function attentionChange(facts: SquareRead, kind: 'listen' | 'ignore' | 'unlisten', actor: string, target: string, now: number): TimedAct<'listen' | 'ignore' | 'unlisten'> | undefined;
 export declare function coreListening(facts: SquareRead, actor: string): readonly string[];
 export declare function compareParticipantActivity(a: Pick<ParticipantSummary, 'name' | 'lastActiveAt'>, b: Pick<ParticipantSummary, 'name' | 'lastActiveAt'>): number;
 export declare function coreParticipants(facts: SquareRead, now: number): ParticipantSummary[];

package/dist/decisions.js

@@ -13,9 +13,7 @@ export function resolveKnownName(facts, name) {
 export function decideJoin(facts, name, now) {
     validateName(name);
     const current = facts.participant(name);
-    const joinedName = current?.name ?? name;
-    return current?.joined ? { joinedName, addParticipant: false }
-        : { joinedName, addParticipant: current === undefined, joinAct: { kind: 'join', actor: joinedName, at: now } };
+    return current?.joined ? undefined : { kind: 'join', actor: current?.name ?? name, at: now };
 }
 function validateActivityName(name) {
     try {
@@ -131,7 +129,7 @@ export function decideAct(facts, input) {
     if (!current.joined)
         throw activityRefusal('not_joined', `${name} has not joined this square`);
     if (header.hardCap !== null && current.sayCount >= header.hardCap)
-        return { type: 'capped', count: current.sayCount, hardCap: header.hardCap };
+        return { type: 'capped' };
     if (reach === 'bell') {
         const recent = facts.recentSayTimes(now - 3600000, 1, name, true);
         if (recent.length > 0)
@@ -162,7 +160,7 @@ export function coreDone(facts, name, body, now) {
     requireStanding(current);
     return { kind: 'done', actor: current.name, at: now };
 }
-function attentionChange(facts, kind, actor, target, now) {
+export function attentionChange(facts, kind, actor, target, now) {
     const current = resolveStanding(facts, actor);
     validateName(target);
     requireStanding(current);
@@ -175,9 +173,6 @@ function attentionChange(facts, kind, actor, target, now) {
     }
     return existing?.kind === kind ? undefined : { kind, actor: current.name, target, at: now };
 }
-export function coreListen(facts, actor, target, now) { return attentionChange(facts, 'listen', actor, target, now); }
-export function coreIgnore(facts, actor, target, now) { return attentionChange(facts, 'ignore', actor, target, now); }
-export function coreUnlisten(facts, actor, target, now) { return attentionChange(facts, 'unlisten', actor, target, now); }
 export function coreListening(facts, actor) {
     const current = resolveStanding(facts, actor);
     return facts.attention(current.name).filter((item) => item.kind === 'listen').map((item) => item.target);

package/dist/delivery-health.js

@@ -32,17 +32,7 @@ export async function classifyDeliveryHealth(squarePath, opts) {
                 || row.outcome === 'dispatching' && (row.expiresAt === undefined || row.expiresAt > now)));
             const terminal = evidence.findLast((row) => row.kind === 'wake' && (row.outcome === 'accepted' || row.outcome === 'unknown'));
             const attemptRow = evidence.findLast((row) => row.kind === 'wake' && (row.outcome === 'accepted' || row.outcome === 'unknown' || row.outcome === 'failed'));
-            const attempt = attemptRow === undefined || seat === undefined || attemptRow.route?.kind === undefined ? undefined : {
-                at: attemptRow.at,
-                attention: { squarePath, recipient: seat.participant, actIndex: note.index },
-                routeKind: attemptRow.route.kind,
-                outcome: attemptRow.outcome,
-                attemptN: attemptRow.attemptN,
-                ...(attemptRow.signature === undefined ? {} : { signature: attemptRow.signature }),
-                ...(attemptRow.message === undefined ? {} : { message: attemptRow.message }),
-                ...(attemptRow.diagnostic === undefined ? {} : { diagnostic: attemptRow.diagnostic }),
-                ...(attemptRow.nativeObservations === undefined ? {} : { nativeObservations: attemptRow.nativeObservations }),
-            };
+            const attempt = attemptRow === undefined || seat === undefined ? undefined : deliveryAttempt(squarePath, attemptRow, { squarePath, recipient: seat.participant, actIndex: note.index });
             const kind = presentation
                 ? 'presented-not-delivered'
                 : terminal?.outcome === 'accepted'
@@ -127,12 +117,12 @@ function formatRelease(release, now) {
     const diagnostic = release.diagnostic === undefined ? '' : ` · ${displayField(JSON.stringify(release.diagnostic))}`;
     return `  · ${formatActivityId(release.attention.actIndex)} → ${displayField(participantIdentity(release.attention.recipient))} · ${route} · ${reason} · ${age}${message}${diagnostic}`;
 }
-function deliveryAttempt(squarePath, row) {
+function deliveryAttempt(squarePath, row, attention = { squarePath, recipient: row.participant, actIndex: Number(row.activity.slice(4)) }) {
     if (row.route?.kind === undefined || row.outcome === 'released' || row.outcome === 'dispatching')
         return undefined;
     return {
         at: row.at,
-        attention: { squarePath, recipient: row.participant, actIndex: Number(row.activity.slice(4)) },
+        attention,
         routeKind: row.route.kind,
         outcome: row.outcome,
         attemptN: row.attemptN,

package/dist/delivery.d.ts

@@ -1,14 +1,6 @@
-import type { DirectedNotificationRoute, StoredAct, WatchLease } from './model.js';
+import type { DirectedNotificationRoute, WatchLease } from './model.js';
 import type { DeliveryEvidence, DirectedHead, ParticipantFact, SquareArtifactPort, SquareRead, WakeRequest } from './ports.js';
 export type { DirectedNotificationRoute } from './model.js';
-export type SayItem = StoredAct & {
-    kind: 'say';
-};
-export interface PlannedNotification {
-    item: SayItem;
-    recipient: string;
-    route: DirectedNotificationRoute;
-}
 /** Exact stored activity projection for transports that send an awareness reminder. */
 export declare function wakePreview(facts: SquareRead, request: WakeRequest): string | undefined;
 export interface RoutedNotification {
@@ -26,8 +18,6 @@ export declare function pendingHead(facts: SquareRead, name: string, index: numb
 export declare function pendingRecipients(facts: SquareRead, index: number): DirectedHead[];
 /** Still-pending directed heads for one recipient, oldest first. Bodies belong to presentation. */
 export declare function pendingHeads(facts: SquareRead, name: string): DirectedHead[];
-/** Complete recipient projection, assembled inside its one transaction. */
-export declare function pendingNotifications(facts: SquareRead, name: string): PlannedNotification[];
 export interface PendingScan {
     readonly roster: readonly ParticipantFact[];
     readonly throughIndex: number;

package/dist/delivery.js

@@ -58,13 +58,6 @@ export function pendingHeads(facts, name) {
     }
     return heads;
 }
-/** Complete recipient projection, assembled inside its one transaction. */
-export function pendingNotifications(facts, name) {
-    const heads = pendingHeads(facts, name), recipient = heads[0]?.recipient ?? name;
-    const routes = new Map(heads.map((head) => [head.index, head.route]));
-    return facts.activities(heads.map((head) => head.index)).flatMap((item) => item.kind === 'say'
-        ? [{ item, recipient, route: routes.get(item.index) }] : []);
-}
 export function capturePendingScan(facts) {
     return { roster: facts.roster().filter((participant) => participant.joined), throughIndex: facts.header().lastActIndex };
 }

package/dist/identity.d.ts

@@ -8,6 +8,5 @@ export declare const SQUARE_IDENTITY: Readonly<{
     cliName: "square";
     pluginId: "square@astrosheep";
     hookCommand: "square codex-hook";
-    hookMarker: "square-codex-hook";
     clientName: "astrosheep_square";
 }>;

package/dist/identity.js

@@ -22,6 +22,5 @@ export const SQUARE_IDENTITY = Object.freeze({
     cliName: 'square',
     pluginId: 'square@astrosheep',
     hookCommand: 'square codex-hook',
-    hookMarker: 'square-codex-hook',
     clientName: 'astrosheep_square',
 });

package/dist/inbox.js

@@ -3,7 +3,7 @@ import { indexedSquareEntries, observeSquareIndex } from './square-index.js';
 import { canonicalPath } from './canonical-path.js';
 import { formatActivityId, parseActivityId } from './square-core.js';
 import { freshWatchLease, WATCH_STALE_MS } from './runtime.js';
-import { pendingHead, pendingNotifications, leaseOwnsNotification } from './delivery.js';
+import { pendingHead, pendingHeads, leaseOwnsNotification } from './delivery.js';
 import { deliveryDeferralExpiry } from './delivery-deferral.js';
 import { attentionBodyIsClipped, renderAttentionPreview, renderSquareReminder } from './attention-presentation.js';
 export function pendingKey(membership, actIndex) {
@@ -146,12 +146,14 @@ async function projectPending(candidates, cache, signal) {
                 const header = facts.header();
                 let cached = cache?.get(location);
                 if (cached?.coordinate !== coordinate || cached.version !== header.revision) {
-                    cached = { coordinate, version: header.revision, value: locatedSeats(facts, location, seats).map(membership => ({
-                            ...membership, notifications: pendingNotifications(facts, membership.seat.participant).map(({ item, route }) => ({
-                                actIndex: item.index, actor: item.actor, at: item.at, body: item.body ?? '(structured activity)', route,
-                                ...(item.delivery === undefined ? {} : { delivery: item.delivery }),
-                            })),
-                        })) };
+                    cached = { coordinate, version: header.revision, value: locatedSeats(facts, location, seats).map(membership => {
+                            const heads = pendingHeads(facts, membership.seat.participant);
+                            const routes = new Map(heads.map(head => [head.index, head.route]));
+                            return { ...membership, notifications: facts.activities(heads.map(head => head.index)).flatMap(item => item.kind === 'say'
+                                    ? [{ actIndex: item.index, actor: item.actor, at: item.at, body: item.body ?? '(structured activity)',
+                                            route: routes.get(item.index), ...(item.delivery === undefined ? {} : { delivery: item.delivery }) }]
+                                    : []) };
+                        }) };
                 }
                 // Cache conversation content, never leases or delivery eligibility: evidence can change
                 // without a conversation revision and must not force body hydration or self-wake retries.

package/dist/notifications.d.ts

@@ -1,6 +1,5 @@
 import { type WakeRouteKind } from './model.js';
 import type { WakeTransportPort } from './ports.js';
-export type { PlannedNotification } from './delivery.js';
 export declare const PRIVILEGED_HOOK_BUDGET_MS = 3000;
 export declare function wakeGraceMs(env?: NodeJS.ProcessEnv): number;
 export type WakeTransports = Readonly<Partial<Record<WakeRouteKind, WakeTransportPort>>>;
@@ -24,3 +23,4 @@ export interface SweepPendingNotificationsOptions {
 }
 /** Select old pending attention at a bounded action boundary for an explicit executor. */
 export declare function sweepPendingNotifications(squarePath: string, opts?: SweepPendingNotificationsOptions): Promise<number[]>;
+export {};

package/dist/ports.d.ts

@@ -63,6 +63,8 @@ export interface DirectedFilter {
     readonly beforeIndex?: number;
     readonly throughIndex?: number;
     readonly unseenOnly?: true;
+    /** Exact own-property scalar equalities, applied before paging or counting. */
+    readonly metadataMatch?: MetadataMatch;
     readonly senders?: readonly string[];
     readonly attentionOnly?: true;
 }
@@ -78,10 +80,6 @@ export interface ReceiptFacts {
     readonly latestAt?: number;
     readonly latestActorActivityIndex?: number;
 }
-export interface ReceiptAssignment {
-    readonly owner: string;
-    readonly index: ActivityIndex;
-}
 export type SeatRef = Pick<Seat, 'participant' | 'owner' | 'generation'>;
 export type ArtifactWriteAuthority = {
     readonly kind: 'send';
@@ -202,7 +200,6 @@ export interface SquareRead {
         readonly at: number;
     } | undefined;
     receiptFacts(requestedName: string, afterIndex: number): ReceiptFacts;
-    receiptAssignments(): readonly ReceiptAssignment[];
     lease(requestedName: string): WatchLease | undefined;
     deliveryDeferrals(participant: string, generation: ActivityId): readonly DeliveryDeferralFact[];
 }

package/dist/sqlite-square.d.ts

@@ -34,7 +34,6 @@ export declare class SqliteSquare {
     join(requested: string, options: JoinOptions, control?: OperationControl): Promise<JoinResult>;
     /** Restore only a standing seat; a concurrent departure or takeover cannot be revived. */
     reattach(name: string, { owner, wakeAddress }: Pick<JoinOptions, 'owner' | 'wakeAddress'>, control?: OperationControl): Promise<Participant | null>;
-    snapshot(control?: OperationControl): Promise<import("./square-facade.js").SquareSnapshot>;
     history(query?: HistoryQuery, control?: OperationControl): Promise<HistoryResult>;
     status(options?: StatusOptions, control?: OperationControl): Promise<StatusResult>;
     participants(options?: ObservationOptions, control?: OperationControl): Promise<ParticipantsResult>;

package/dist/sqlite-square.js

@@ -6,14 +6,14 @@ import { squareLocation } from './square-location.js';
 import crypto from 'node:crypto';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { activityMetadataHasContent, InternalSquareError, SquareError, isSquareError, nameKey, sameName, validateActivityMetadata, validateName } from './model.js';
-import { coreDone, coreIgnore, coreListen, coreListening, coreUnlisten, decideAct, decideJoin, resolveKnownName, validateDoneBody } from './decisions.js';
+import { attentionChange, coreDone, coreListening, decideAct, decideJoin, resolveKnownName, validateDoneBody } from './decisions.js';
 import { WATCH_HEARTBEAT_MS, inSquareCount, presenceAnchor } from './runtime.js';
 import { catchLimit, decideCatch, observeCatchSelection, selectCatchPage } from './catch-decisions.js';
 import { expressionContext } from './activity-feed.js';
 import { expressHint } from './hints.js';
 import { ATTENTION_BODY_MAX } from './attention-presentation.js';
 import { asSeatRef, participantAuthority, requireOwner, requireJoinName } from './seats.js';
-import { recoveryObservation, entryPresentation, snapshot, queryStatus, queryParticipants, catchPresence, parseRequiredActivityId, toPublicActivity, publicActivities, selectHistory, NON_READ, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
+import { recoveryObservation, entryPresentation, queryStatus, queryParticipants, catchPresence, parseRequiredActivityId, toPublicActivity, toPerceivedActivity, publicActivities, selectHistory, NON_READ, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
 import { sessionInboxCounts } from './inbox.js';
 import { rememberSquarePath, squareIndexPath } from './square-index.js';
 import { deliverPending } from './delivery-operations.js';
@@ -216,7 +216,7 @@ export class SqliteSquare {
             checkControl(control);
             const seat = this.seat, now = square.clock();
             return (await square.artifact.transactAs(participantAuthority(seat), facts => {
-                const act = verb === 'listen' ? coreListen(facts, name, target, now) : verb === 'ignore' ? coreIgnore(facts, name, target, now) : coreUnlisten(facts, name, target, now);
+                const act = attentionChange(facts, verb, name, target, now);
                 const activity = act === undefined ? null : toPublicActivity(facts.land(act));
                 return { activity, ...(!options.observe ? {} : { observation: {
                             ...square.observation(inSquareCount(facts), name, now), participant: name,
@@ -344,6 +344,37 @@ export class SqliteSquare {
                     await releaseWatchLease(square.artifact, seat, leaseId).catch(() => undefined);
             }
         }
+        async pending(options = {}, control) {
+            checkControl(control);
+            const limit = options.limit ?? 100;
+            if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+                throw new SquareError('invalid_args', 'Pending limit must be a positive integer no greater than 100.');
+            const match = options.match === undefined ? undefined : validateMetadataMatch(options.match);
+            const square = this.owner;
+            return (await square.artifact.read(facts => {
+                assertCurrentSeat(facts, asSeatRef(this.seat));
+                const filter = { unseenOnly: true, ...(match === undefined ? {} : { metadataMatch: match }) };
+                const heads = facts.directed(this.name, filter, { edge: 'oldest', limit });
+                const activities = facts.activities(heads.items.map(head => head.index))
+                    .map(activity => toPerceivedActivity(facts, activity, this.name));
+                return { activities, remaining: facts.directedCount(this.name, filter) - activities.length };
+            }, control?.signal)).value;
+        }
+        async ack(ids, control) {
+            checkControl(control);
+            if (!Array.isArray(ids))
+                throw new SquareError('invalid_args', 'Ack requires an array of activity IDs.');
+            const indexes = [...new Set(Array.from(ids, parseRequiredActivityId))], square = this.owner;
+            return (await square.artifact.transactAs(participantAuthority(this.seat), facts => {
+                for (const index of indexes) {
+                    if (facts.directedAt(this.name, index) === undefined)
+                        throw new SquareError('invalid_args', `${formatActivityId(index)} is not addressed to you.`, {
+                            reason: 'not_addressed', activityId: formatActivityId(index),
+                        });
+                }
+                return { consumed: facts.markSeen(this.name, indexes, square.clock()) };
+            }, control?.signal)).value;
+        }
         async deferDelivery(input, control) {
             checkControl(control);
             const match = validateMetadataMatch(input?.match), duration = validateDeferralDuration(input?.durationMs);
@@ -416,7 +447,7 @@ export class SqliteSquare {
             const standing = facts.roster().filter(p => p.joined), resolvedTo = [], missing = [];
             for (const target of unique) {
                 const recipient = standing.find(p => sameName(p.name, target));
-                if (recipient === undefined || facts.seat(recipient.name)?.attachment !== 'attached')
+                if (recipient === undefined)
                     missing.push(target);
                 else
                     resolvedTo.push(recipient.name);
@@ -484,10 +515,10 @@ export class SqliteSquare {
                     kind = 'reconnected';
                 }
                 if (kind !== 'reconnected') {
-                    const decision = decideJoin(facts, participant, now);
-                    if (decision.joinAct === undefined)
+                    const joinAct = decideJoin(facts, participant, now);
+                    if (joinAct === undefined)
                         throw new SquareError('already_joined', `${participantIdentity(participant)} could not be joined`);
-                    activity = toPublicActivity(facts.land(decision.joinAct));
+                    activity = toPublicActivity(facts.land(joinAct));
                 }
                 const seat = facts.seat(participant);
                 if (seat === undefined)
@@ -532,7 +563,6 @@ export class SqliteSquare {
             await this.publishSeat(owner);
         return seat === null ? null : this.handle(seat);
     }
-    async snapshot(control) { return (await this.artifact.read(facts => snapshot(facts, this.clock()), control?.signal)).value; }
     async history(query = {}, control) {
         if (query.limit !== undefined && query.limit !== null && (!Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > HISTORY_MAX_LIMIT))
             throw new SquareError('invalid_args', `History limit must be a positive integer no greater than ${HISTORY_MAX_LIMIT}`);

package/dist/square-facade.d.ts

@@ -86,6 +86,20 @@ export interface CatchOptions extends ObservationOptions {
     readonly limit?: number;
     readonly replace?: boolean;
 }
+export interface PendingOptions {
+    readonly match?: MetadataMatch;
+    /** Oldest first; defaults to 100, maximum 100. */
+    readonly limit?: number;
+}
+export interface PendingResult {
+    readonly activities: readonly PerceivedActivity[];
+    /** Matching unconsumed activities outside this page. */
+    readonly remaining: number;
+}
+export interface AckResult {
+    /** Newly consumed addressed IDs; repeated acknowledgement is a no-op. */
+    readonly consumed: number;
+}
 export type CatchReason = 'drained' | 'idle' | 'capped' | 'quorum' | 'replaced' | 'already-active';
 export interface CatchResult {
     readonly activities: readonly PerceivedActivity[];
@@ -145,14 +159,6 @@ export interface HistoryResult {
     readonly activities: readonly Activity[];
     readonly observation?: HistoryObservation;
 }
-export interface SquareSnapshot {
-    readonly context: string;
-    readonly actCount: number;
-    readonly hardCap: number | null;
-    readonly throttlePerMinute?: number;
-    readonly participants: readonly Pick<ParticipantSummary, 'name' | 'presence' | 'listening'>[];
-    delivered(name: string, id: ActivityId): boolean;
-}
 export interface OpenOptions {
     readonly clock?: () => number;
     readonly wakeTransport?: WakeTransportPort | false;
@@ -195,6 +201,8 @@ export interface Participant {
     unlisten(target: string, options?: ObservationOptions, control?: OperationControl): Promise<ListenerChangeResult>;
     listening(options?: ObservationOptions, control?: OperationControl): Promise<ListeningResult>;
     catch(options?: CatchOptions, control?: OperationControl): Promise<CatchResult>;
+    pending(options?: PendingOptions, control?: OperationControl): Promise<PendingResult>;
+    ack(ids: readonly ActivityId[], control?: OperationControl): Promise<AckResult>;
     /** Leave without a message. Only an omitted or empty body is accepted. */
     done(body?: string, options?: ObservationOptions, control?: OperationControl): Promise<LifecycleResult>;
     deferDelivery(input: Readonly<{

package/dist/square-sqlite.js

@@ -539,6 +539,27 @@ export function createSqliteDriver(db) {
         }
         if (filter.attentionOnly)
             base.sql += " AND d.route IN ('mention','reply','bell')";
+        if (filter.metadataMatch !== undefined) {
+            // Walk object keys rather than JSON-path strings: dots, quotes and array-like
+            // keys are literal, and arrays must never act as metadata objects.
+            base.sql += ` AND NOT EXISTS (
+                SELECT 1 FROM json_each(?) field WHERE NOT EXISTS (
+                    WITH RECURSIVE walk(value,type,depth) AS (
+                        SELECT json_extract(a.payload_json,'$.metadata'),json_type(a.payload_json,'$.metadata'),0
+                        UNION ALL
+                        SELECT child.value,child.type,walk.depth+1
+                        FROM walk JOIN json_each(CASE WHEN walk.type='object' THEN walk.value ELSE '{}' END) child
+                          ON child.key=json_extract(field.value,'$.path['||walk.depth||']')
+                        WHERE walk.depth<json_array_length(field.value,'$.path')
+                    )
+                    SELECT 1 FROM walk WHERE depth=json_array_length(field.value,'$.path')
+                      AND (type=json_type(field.value,'$.equals')
+                        OR type IN ('integer','real') AND json_type(field.value,'$.equals') IN ('integer','real'))
+                      AND value IS json_extract(field.value,'$.equals')
+                )
+            )`;
+            base.args.push(encode(filter.metadataMatch.fields));
+        }
         return base;
     }
     function directedHead(row, recipient) {
@@ -691,7 +712,6 @@ export function createSqliteDriver(db) {
             const k = encode(owner(name)), r = one('SELECT MAX(at) AS latest FROM receipts WHERE owner_json=?', [k]), e = one('SELECT MAX(r.act_index) AS latest FROM receipts r JOIN activities a ON a.act_index=r.act_index WHERE r.owner_json=? AND r.act_index>? AND a.actor_json IS NOT NULL', [k, integer(afterIndex, -1)]);
             return immutable({ ...(r.latest === null ? {} : { latestAt: finite(r.latest) }), ...(e.latest === null ? {} : { latestActorActivityIndex: integer(e.latest) }) });
         },
-        receiptAssignments: () => immutable(all('SELECT owner_json,act_index FROM receipts ORDER BY owner_json,act_index').map(r => ({ owner: decoded(r.owner_json, true), index: integer(r.act_index) }))),
         deliveryDeferrals(name, generation) {
             const canonical = owner(name);
             const current = read.seat(canonical);

package/dist/views.d.ts

@@ -1,7 +1,7 @@
 import { type ActivityId } from './square-core.js';
 import { type StoredAct } from './model.js';
 import type { ActivityFilter, SquareRead } from './ports.js';
-import type { Activity, ArchiveRecord, PerceivedActivity, HistoryQuery, HistoryContinuation, ParticipantsResult, SquareSnapshot, EntryPresentation, StatusResult, SquareObservation, CatchPresence } from './square-facade.js';
+import type { Activity, ArchiveRecord, PerceivedActivity, HistoryQuery, HistoryContinuation, ParticipantsResult, EntryPresentation, StatusResult, SquareObservation, CatchPresence } from './square-facade.js';
 export declare const HISTORY_DEFAULT_LIMIT = 10;
 export declare const HISTORY_MAX_LIMIT = 100;
 export declare const NON_READ: readonly ["join", "done", "say", "listen", "ignore", "unlisten"];
@@ -17,7 +17,6 @@ export declare function selectHistory(facts: SquareRead, query: HistoryQuery, li
     totalMatches: number;
 };
 export declare function publicActivities(activities: readonly ArchiveRecord[]): Activity[];
-export declare function snapshot(facts: SquareRead, now: number): SquareSnapshot;
 export declare function recoveryObservation(facts: SquareRead, name: string, now: number): {
     participant: string;
     activitySummaries: import("./square-facade.js").UnreadActivitySummary[];

package/dist/views.js

@@ -111,15 +111,6 @@ export function selectHistory(facts, query, limit, kinds, presentation = true) {
 export function publicActivities(activities) {
     return activities.flatMap((activity) => activity.kind === 'read' ? [] : [toPublicActivity(activity)]);
 }
-export function snapshot(facts, now) {
-    const header = facts.header();
-    const names = new Map(facts.roster().map((p) => [nameKey(p.name), p.name]));
-    const receipts = new Set(facts.receiptAssignments().map((r) => JSON.stringify([r.owner, r.index])));
-    return { context: [...header.preamble, ...header.warmup].join('\n'), actCount: facts.activityCount({ kinds: NON_READ }), hardCap: header.hardCap,
-        ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
-        participants: coreParticipants(facts, now).filter((p) => p.presence !== 'never-joined').map(({ name, presence, listening }) => ({ name, presence, listening })),
-        delivered(name, id) { return receipts.has(JSON.stringify([names.get(nameKey(name)) ?? name, parseRequiredActivityId(id)])); } };
-}
 export function recoveryObservation(facts, name, now) {
     const known = resolveKnownName(facts, name);
     return { participant: known, activitySummaries: unreadActivitySummaries(facts, known, now), standingCount: inSquareCount(facts),

package/guides/operation-cancellation.md

@@ -8,7 +8,11 @@ Library operations accept a final non-serializable control value:
 
 The signal is checked before lifecycle work and before artifact mutation, and it is propagated through artifact reads, transactions, change waits, and ownership lock acquisition. An idle `catch` rejects promptly when cancelled; it does not wake later and consume activity. Cancellation before an artifact transition prevents mutation.
 
-Commit boundaries are one-way. Once an activity or observation commits, later cancellation cannot roll it back or turn the result into a retry. A caller may discard the response after the commit, but the committed activity remains recoverable through `history` or a later `catch`; Square does not add a second consumption acknowledgement phase.
+Commit boundaries are one-way. Once an activity or observation commits, later cancellation cannot
+roll it back or turn the result into a retry. A caller may discard the response after the commit,
+but the committed activity remains recoverable through `history` or a later `catch`; catch does not
+require a second acknowledgement. The separate `pending` query never consumes; its optional
+follow-up `ack(ids)` commits exact receipts with the same cancellation boundary.
 
 The single catch lease and independent delivery-deferral leases have distinct lifetimes. Cancelling
 an active catch releases only that catch's lease. Cancelling a deferral operation before commit

package/guides/primitive-status-consolidation.md

@@ -72,7 +72,7 @@ The amended guidance's reachable-latest clause is applied: the selector remains
 - `test/core.test.js`: status and participants continue sharing actual authored and receipt times, including a fresh rejoin and watcher.
 - `test/process/square-cli-render.test.js`: the compact ten-person preview now includes a valid historical never-joined actor in the artifact. Status still hides that actor but its executable continuation uses the full count 14 rather than filtered count 13; participants prints the complete roster. Existing exact rejoin, attention, clipping/public-id continuation and presence feedback remain covered.
 
-No observation timing change is intended: optional viewer discovery still precedes status's resource read; the clock is sampled once inside the transaction, and all domain data, classification, perception and rendering annotations are assembled in that read. Queries perform no I/O or mutations themselves. SDK participant/snapshot shapes and MCP serialization of data remain unchanged. No join/claim is introduced.
+No observation timing change is intended: optional viewer discovery still precedes status's resource read; the clock is sampled once inside the transaction, and all domain data, classification, perception and rendering annotations are assembled in that read. Queries perform no I/O or mutations themselves. At the time, SDK participant/snapshot shapes and MCP serialization of data remained unchanged; the SDK snapshot was subsequently retired. No join/claim is introduced.
 
 Production reference search for `coreStatus|StatusObservation|StatusPresentation|ParticipantsPresentation|statusPresentation|participantsPresentation|StatusResult` returns no matches. Neither status nor participants has a duplicate roster in its projection. `git diff --check` passes.
 

package/guides/receive-primitive.md

@@ -79,8 +79,10 @@ primitive entrypoints without constructing Square.
 
 ## Square composition
 
-Square uses these functions for production landing, catch and `markSeen` against
-its existing activity, audience and receipt tables. Numeric activity indexes stay
+Square uses these functions for production landing, catch and `markSeen` (including explicit
+`Participant.ack`) against its existing activity, audience and receipt tables. `Participant.pending`
+uses the same addressed/unconsumed relation without writing receipts; optional metadata matching
+is applied by storage before the page limit. Numeric activity indexes stay
 internal keys; the primitive does not know Square IDs. Square retains validation,
 limits, filtering, perception, ownership, leases, hints and error mapping. The
 empty-catch read probe does not hydrate or acquire a writer; a nonempty probe is

package/guides/row-runtime-delivery-evidence.md

@@ -30,9 +30,9 @@ rg -n 'validateSquareState|exportSqliteState|initializeSqlite|writeSquareSnapsho
 - `square-state.ts` retains legacy validation for the separately implemented migration and test oracle. Normal v1 recognition validates framing and refuses with `migration_required`; it never decodes v1 history. Common per-activity validation is also used by the row codec.
 - `artifact.ts::readSquareSnapshot` and `square-sqlite.ts::exportSqliteState` are explicit export/integrity capabilities. Doctor intentionally reads all authority and compares maintained indices against a rebuild. Neither is a hot-runtime fallback.
 - `createSquareSnapshot` initializes a new artifact. `writeSquareSnapshot/writeSquareFile` are explicit build `--force`/fixture import, not whole-state transaction callbacks. Existing v1 still refuses before destructive work. `initializeSqlite` also supplies the migration's shared rebuild; it calls the same `deriveLanding`, not another production fold.
-- Public SDK `snapshot().delivered()` copies raw receipt assignments into a detached exact-owner Set; it does not retain a query or transaction capability and copies no activity history.
+- Historical (retired SDK API): `snapshot().delivered()` copied raw receipt assignments into a detached exact-owner Set; it does not retain a query or transaction capability and copies no activity history.
 - `.state` matches elsewhere are participant/admission states, transport outcomes or Claude's native `$.state` API, not artifact snapshots. `packages/agent-delivery` remains untouched.
-- `test/fixtures/legacy-square-core.js` is a frozen test-only v1 replay oracle. `square_snapshot` in the benchmark is instrumentation for detecting forbidden legacy reads, not a runtime path.
+- `square_snapshot` in the benchmark is instrumentation for detecting forbidden legacy reads, not a runtime path.
 
 ### Production source size
 
@@ -59,7 +59,7 @@ Evidence locations:
 
 | Invariant | Tests |
 |---|---|
-| Maintained roster/attention/audience equals independent v1 replay, including gaps, mixed spelling, reply/mention/listen/ignore/bell/done/rejoin priority and order | `test/row-domain.test.js`, frozen `test/fixtures/legacy-square-core.js` |
+| Landing audience priority and directed attention, including mixed spelling, reply/mention/listen/ignore/bell and departure | `test/row-domain.test.js` |
 | Sparse receipts, exact raw owners/orphans, unseen hole vs later catch, repeat no-op, filtered remaining, historical catch vs latest-join pending, distinct cursor/presence | `test/row-domain.test.js`, `test/perception-projection.test.js` |
 | Exact v2 schema, optional field preservation, immutable detached facts, expired capabilities, synchronous callbacks, caught storage failure rollback, no-op revision, selected corruption vs doctor | `test/artifact.test.js`, `test/core.test.js` |
 | Two real processes serialize catches; process death rolls activity and indices back; busy COMMIT retains callback/result; abort preserves reason; revision read has a positive SQL control | `test/sqlite-storage.test.js` |

package/guides/row-storage-design.md

@@ -1,5 +1,7 @@
 # Row-oriented artifact design
 
+> Historical design: the public SDK `Square.snapshot()` and its closure were retired. Snapshot-specific proposals below record the design at the time, not the current API.
+
 **Historical accepted design for artifact format 2.** The current runtime uses format 3 for the
 `unlisten` event; see [Square API](square-api.md#artifact-format-and-explicit-migration) for current
 format/migration behavior. The schema and delivery-stage terms below record the original row-storage
@@ -428,7 +430,9 @@ No production structure below carries `.state`, all `.activities`, or a deferred
 | public Square.snapshot().delivered(name,id) | explicit receiptAssignments + detached roster resolution + small header/status in ONE read txn, as below. Other production callers must not use this for count/standing. |
 | doctor / explicit import/export tests | full selected-row validation and replay comparison of indices; detached result includes standing count, not state for CLI header. Legacy validator lives only in explicit migration/test oracle. No automatic repair. |
 
-### Public SDK snapshot closure
+### Public SDK snapshot closure (retired)
+
+This historical design described the removed SDK `Square.snapshot()` API; it is no longer supported.
 
 Keep synchronous arbitrary `delivered(name,id)`. `snapshot()` intentionally copies ALL raw receipt assignments into a private detached Set keyed by JSON.stringify([rawOwner,index]), along with an immutable nameKey->first-roster-spelling map. Closure validates/parses id with current parseRequiredActivityId, resolves `map[nameKey(name)] ?? name`, and tests that exact owner/index set. This covers dormant raw owner keys, orphan assigned coordinates, unknown-name fallback, and arbitrary later calls after port close. It does not query a DB or retain SquareRead. Later writes do not alter this snapshot. No receipt times/activity bodies are copied. This O(receipts) exception is necessary for the existing synchronous API, and is limited to explicit SDK snapshot calls; lifecycle/status/poll/render use narrower helpers.
 

package/guides/square-api.md

@@ -197,7 +197,7 @@ shared dispatcher's timeout or retry policy.
 
 ## One set of operations and defaults
 
-Square owns `history`, `status`, `participants`, `snapshot`, `stream`, and recovery observations.
+Square owns `history`, `status`, `participants`, `stream`, and recovery observations.
 A file-backed `stream` follows the path with a fresh artifact read for each page, so atomic file
 replacement is visible even while the resource holds its original connection. Its iterator owns
 its observation lifetime: `return()` interrupts a pending pull; closing a local Square does not close
@@ -211,7 +211,7 @@ their landed directed activities and adds `perception` and the landing route `vi
 (`mention`, `reply`, `attention`, or `bell`). Perception follows the viewer's actual landed audience;
 `via` is absent when no directed route exists. Stream starts at a bounded tail or after an `ActivityId`
 like `act/12`; it never consumes activity.
-Participant owns `express`, `catch`, `listen`, `unlisten`, `ignore`, `listening`, `done`,
+Participant owns `express`, `catch`, `pending`, `ack`, `listen`, `unlisten`, `ignore`, `listening`, `done`,
 `deferDelivery`, `renewDeliveryDeferral`, and `releaseDeliveryDeferral`. History belongs only to
 Square; there is no `Participant.history`.
 
@@ -271,6 +271,62 @@ Operations that accept an `OperationControl` use a final argument with `signal`
 `onProgress`. Listener/lifecycle operations take optional observation options before that argument;
 participant selection, seat discovery and host cleanup methods do not take an `OperationControl`.
 
+## Pending query and exact acknowledgement
+
+`Participant.pending(options?, control?)` and `Participant.ack(ids, control?)` separate a read-only
+query from explicit consumption. `ChannelEndpoint` from `@astrosheep/square/channel` exposes the
+identical methods by forwarding to its captured Participant; it has no independent inbox or storage.
+
+`Channel.send` / `Square.send` address joined members, including detached members. Attachment gates
+proactive wake, not landing: a detached recipient retains its unread addressed activity without a
+wake and can query/ack it after reattachment. Recipient validation remains all-or-nothing; a missing
+or departed recipient rejects the entire send without landing activity or waking other recipients.
+
+```ts
+import type { ChannelEndpoint, MetadataMatch } from '@astrosheep/square/channel';
+
+async function drain(endpoint: ChannelEndpoint, match: MetadataMatch) {
+  for (;;) {
+    const page = await endpoint.pending({ match });
+    if (page.activities.length === 0) break;
+    // Process the entire page successfully before acknowledging its exact IDs.
+    for (const activity of page.activities) await processNotice(activity);
+    const { consumed } = await endpoint.ack(page.activities.map(activity => activity.id));
+    // consumed may be smaller if another consumer acknowledged some IDs first.
+  }
+}
+```
+
+- `pending({match?, limit?} = {}, control?)` returns
+  `{activities: readonly PerceivedActivity[], remaining: number}`. It selects only landed,
+  addressed, unconsumed says, oldest first. Body, metadata, delivery information, perception and
+  route use the same public records as catch; bodies are full stored bodies, not clipped previews.
+- Limit defaults to 100 and must be an integer from 1 through 100. The optional `MetadataMatch`
+  uses exactly the nested own-property scalar equality semantics described below (AND across fields).
+  Storage applies addressedness, consumption and metadata matching **before** limiting.
+  `remaining` counts matching unconsumed activities outside the returned page, in the same read
+  transaction. It is not the global unread count or a durable cursor.
+- A pending query consumes nothing, changes no read horizon and writes no delivery/presentation
+  evidence. Deferrals, catch leases, cancellation and prior clipped presentation do not hide these
+  explicit reads. Like catch, pending includes historical addressed receipt holes before a rejoin;
+  it is not the proactive delivery eligibility query.
+- `ack(ids: readonly ActivityId[], control?)` returns `{consumed: number}`, the count of newly
+  consumed exact IDs. It validates that **every** supplied ID is addressed to this participant before
+  recording any receipts. Malformed, nonexistent or unaddressed IDs reject the whole batch with
+  `invalid_args` (`reason: 'not_addressed'` for valid but unaddressed IDs). There is no implicit prefix
+  acknowledgement, no match reselection and no requirement for an earlier pending call.
+- Duplicate IDs, repeated acknowledgement and an empty array are idempotent. Existing receipt
+  timestamps remain unchanged. Acknowledgement uses the same sparse receipts as catch/full
+  presentation, so it removes those IDs from pending and ordinary catch, but exact catch remains
+  repeatable. It does **not** assert wake acceptance or presentation and writes no such evidence.
+- Both operations require their captured current owner, generation and attached seat; even an empty
+  query/ack cannot reuse a detached, retired or replaced handle. No storage format change is needed.
+  Cancellation before the receipt transaction prevents consumption; a committed ack is not undone.
+- To drain all matching notices, keep querying and acknowledging pages until an **empty** page.
+  Acknowledging one page exposes the next without a cursor. Do not silently stop after the default
+  page or treat a snapshot `remaining: 0` as proof that concurrent producers have stopped. Query and
+  ack are separate operations, not an exclusive claim or an exactly-once external-effect guarantee.
+
 ## Temporary proactive delivery deferral
 
 SDK Participants expose three operations. There are no CLI/MCP/Pi authoring
@@ -307,9 +363,9 @@ try {
   releasing one cannot end another. A captured current owner/join generation is required for every
   mutation. Stale handles retain the ownership refusal; done/takeover/rejoin retire old leases.
 - Lease writes change delivery revision, not conversation history. They do not create a receipt,
-  change audience or unread counts, hide an archive record, or prohibit explicit catch. Catch alone
-  consumes normally; a caught record is not replayed when a deferral ends. The catch lease is a
-  separate, single quiet-wait lease with its existing filters and lifecycle.
+  change audience or unread counts, hide an archive record, or prohibit explicit catch/pending/ack.
+  Catch and ack consume normally; a consumed record is not replayed when a deferral ends. The catch
+  lease is a separate, single quiet-wait lease with its existing filters and lifecycle.
 - Producer/sweep, atomic claims, session/native projections, final pre-send checks and proactive
   presentation all share current-generation unexpired matching. Suppressed items get no seen or
   presented receipt. An active pending observer rechecks on release and the earliest relevant
@@ -339,8 +395,8 @@ or history/status presentation annotations.
 Express captures optional unread context before the attempt: the latest five directed,
 unseen activities after the current join, each preview capped at 400 Unicode characters,
 plus the count outside that preview. It hydrates only that page, not the entire cursor suffix.
-This is a nonconsuming preview even when a short body fits in full; only `catch` or the
-normal full-notification presentation path consumes it. Count and time facts come
+This is a nonconsuming preview even when a short body fits in full; consumption requires `catch`,
+explicit `ack`, or the normal full-notification presentation path. Count and time facts come
 from the committed transaction. Listener and lifecycle observations likewise use their mutation's
 facts, with no postcommit context read. Join uses its mutation's essential facts and treats optional
 entry/history enrichment as best-effort: `observation.enrichmentUnavailable` is explicit and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.96",
+  "version": "0.3.97",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
@@ -46,7 +46,6 @@
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^22",
     "@types/ws": "^8.18.1",
-    "square-v1": "npm:@astrosheep/square@0.3.70",
     "typescript": "^5.8",
     "ws": "^8.21.3"
   },

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.96",
+  "version": "0.3.97",
   "description": "Native Claude Code inbox delivery for Square participants",
   "types": "./types.d.ts",
   "author": {

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.96",
+  "version": "0.3.97",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/plugins/codex/hooks/hooks.json

@@ -1,16 +1,16 @@
 {
   "hooks": {
     "SessionStart": [
-      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5 }] }
+      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5, "statusMessage": "Square" }] }
     ],
     "SessionResume": [
-      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5 }] }
+      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5, "statusMessage": "Square" }] }
     ],
     "SessionEnd": [
-      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 3 }] }
+      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 3, "statusMessage": "Square" }] }
     ],
     "UserPromptSubmit": [
-      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5 }] }
+      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5, "statusMessage": "Square" }] }
     ],
     "PostToolUse": [
       {
@@ -19,7 +19,7 @@
             "type": "command",
             "command": "square codex-hook",
             "timeout": 5,
-            "statusMessage": "square-codex-hook"
+            "statusMessage": "Square"
           }
         ]
       }
@@ -31,7 +31,7 @@
             "type": "command",
             "command": "square codex-hook",
             "timeout": 5,
-            "statusMessage": "square-codex-hook"
+            "statusMessage": "Square"
           }
         ]
       }