@astrosheep/square 0.3.94 → 0.3.95

package/dist/http-delivery.js

@@ -0,0 +1,101 @@
+import { wakePreview } from './delivery.js';
+/** Configuration only: probing never contacts the receiver. */
+function configuration(route, env) {
+    if (route.kind !== 'http')
+        return undefined;
+    try {
+        const url = new URL(route.address.url);
+        if (!['http:', 'https:'].includes(url.protocol) || !url.hostname || url.username || url.password
+            || route.address.url.includes('#'))
+            return undefined;
+        const headers = new Headers({ 'Content-Type': 'application/json' });
+        const tokenEnv = route.address.tokenEnv;
+        if (tokenEnv !== undefined) {
+            const token = tokenEnv.trim() ? env[tokenEnv] : undefined;
+            // RFC 6750 bearer credentials; whitespace/control characters cannot become headers.
+            if (!token || token !== token.trim() || !/^[A-Za-z0-9._~+\/-]+=*$/.test(token))
+                return undefined;
+            headers.set('Authorization', `Bearer ${token}`);
+        }
+        return { url: route.address.url, headers };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** HTTP accepts wake custody only; it never consumes or presents Square activity. */
+export class HttpWakeTransport {
+    opts;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    async probe(route) {
+        return configuration(route, this.opts.env ?? process.env) !== undefined
+            ? true : { outcome: 'not-capable', diagnostic: 'HTTP wake configuration unavailable.' };
+    }
+    async attempt(request, timeoutMs, beforeSend) {
+        const deadline = Date.now() + timeoutMs;
+        if (request.route.kind !== 'http')
+            return { outcome: 'not-capable' };
+        const config = configuration(request.route, this.opts.env ?? process.env);
+        if (config === undefined)
+            return { outcome: 'failed', signature: 'http_config_rejected', message: 'Invalid HTTP wake configuration.' };
+        const controller = new AbortController();
+        let sent = false;
+        const budgetUnavailable = () => sent
+            ? { outcome: 'unknown', signature: 'http_send_timeout', message: 'HTTP wake acceptance is unknown after timeout.' }
+            : { outcome: 'failed', signature: 'http_pre_send_timeout', message: 'HTTP wake budget elapsed before sending.' };
+        if (!Number.isFinite(timeoutMs) || Date.now() >= deadline)
+            return budgetUnavailable();
+        let timer;
+        const timeout = new Promise(resolve => {
+            timer = setTimeout(() => { controller.abort(); resolve(budgetUnavailable()); }, Math.max(0, deadline - Date.now()));
+        });
+        const send = async () => {
+            try {
+                const preview = request.artifact === undefined ? undefined
+                    : (await request.artifact.read(facts => wakePreview(facts, request), controller.signal)).value;
+                if (preview === undefined)
+                    return { outcome: 'not-capable', diagnostic: 'No pending Square activity to preview.' };
+                const body = JSON.stringify({
+                    location: request.location, participant: request.participant, activity: request.activity, actor: request.actor,
+                    ...(request.attemptN === undefined ? {} : { attemptN: request.attemptN }), preview,
+                });
+                if (controller.signal.aborted || Date.now() >= deadline)
+                    return budgetUnavailable();
+                if (!(await beforeSend()))
+                    return { outcome: 'not-capable' };
+                // Preview and the final gate spend the same absolute budget as the request.
+                if (controller.signal.aborted || Date.now() >= deadline)
+                    return budgetUnavailable();
+                sent = true;
+                const response = await (this.opts.fetch ?? fetch)(config.url, {
+                    method: 'POST', headers: config.headers, body, redirect: 'manual', signal: controller.signal,
+                });
+                // Status is the whole acknowledgement; never wait for or buffer a receiver body.
+                void response.body?.cancel().catch(() => undefined);
+                if (response.status >= 200 && response.status < 300)
+                    return { outcome: 'accepted', signature: 'http_accepted' };
+                return {
+                    outcome: 'failed', signature: response.status >= 500 && response.status < 600 ? 'http_status_transient' : 'http_status_rejected',
+                    message: `HTTP wake returned status ${response.status}.`,
+                };
+            }
+            catch {
+                // URLs, query credentials and raw fetch exceptions must never reach evidence.
+                if (controller.signal.aborted)
+                    return budgetUnavailable();
+                return sent
+                    ? { outcome: 'unknown', signature: 'http_send_unknown', message: 'HTTP wake acceptance is unknown after a network error.' }
+                    : { outcome: 'failed', signature: 'http_pre_send_failed', message: 'HTTP wake could not be prepared.' };
+            }
+        };
+        try {
+            return await Promise.race([send(), timeout]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+}

package/dist/model.d.ts

@@ -1,7 +1,7 @@
 import type { Act, ActivityId } from './square-core.js';
 export { formatActivityId, parseActivityId } from './square-core.js';
 export type { Act, ActivityId, Audience, Reach } from './square-core.js';
-export declare const WAKE_ROUTE_KINDS: readonly ["opencode-server", "codex-queue", "claude-native", "paseo"];
+export declare const WAKE_ROUTE_KINDS: readonly ["opencode-server", "codex-queue", "claude-native", "paseo", "http"];
 export type WakeRouteKind = typeof WAKE_ROUTE_KINDS[number];
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
@@ -41,7 +41,7 @@ export interface WakeRoute {
     address: Record<string, string>;
     updatedAt: number;
 }
-export type SquareErrorCode = 'invalid_name' | 'invalid_args' | 'unknown_participant' | 'not_joined' | 'already_joined' | 'already_done' | 'held' | 'capped' | 'throttled' | 'bell_quota' | 'behind' | 'io' | 'unavailable';
+export type SquareErrorCode = 'invalid_name' | 'invalid_args' | 'unknown_participant' | 'not_joined' | 'already_joined' | 'already_done' | 'capped' | 'throttled' | 'bell_quota' | 'behind' | 'io' | 'unavailable';
 export type InternalSquareErrorCode = SquareErrorCode | 'not_found' | 'cap_reached' | 'conflict' | 'pending_peer';
 export interface SquareErrorFacts {
     /** Copyable recovery for a missing, detached or foreign seat. */
@@ -59,8 +59,6 @@ export interface SquareErrorFacts {
     /** Whether the artifact holds that activity at all; an unknown id needs an ordinary page. */
     activityExists?: boolean;
     pending?: number;
-    holder?: string;
-    holdReason?: string;
     retryAfterMs?: number;
 }
 declare class SquareErrorBase<Code extends string> extends Error {
@@ -100,7 +98,7 @@ export interface WatchLease {
     expiresAt: number;
     filter?: WatchLeaseFilter;
 }
-export type DirectedNotificationRoute = 'mention' | 'reply' | 'attention' | 'bell';
+export type DirectedNotificationRoute = import('./attention.js').AudienceRoute;
 export interface InboxNotification {
     actIndex: number;
     actor: string;
@@ -127,7 +125,7 @@ export type PublicAct = Extract<StoredAct, {
     kind: 'say' | 'done';
 }>;
 export type RoomChangeAct = Extract<StoredAct, {
-    kind: 'join' | 'done' | 'hold' | 'resume' | 'listen' | 'ignore' | 'unlisten';
+    kind: 'join' | 'done' | 'listen' | 'ignore' | 'unlisten';
 }>;
 export declare function formatHardCap(hardCap: HardCap): string;
 export declare function parseParticipantList(value: string): string[];

package/dist/model.js

@@ -1,6 +1,6 @@
 // Shared model and constants for Square.
 export { formatActivityId, parseActivityId } from './square-core.js';
-export const WAKE_ROUTE_KINDS = ['opencode-server', 'codex-queue', 'claude-native', 'paseo'];
+export const WAKE_ROUTE_KINDS = ['opencode-server', 'codex-queue', 'claude-native', 'paseo', 'http'];
 export const ACTIVITY_METADATA_MAX_BYTES = 16 * 1024;
 export const ACTIVITY_METADATA_MAX_DEPTH = 256;
 /** Validate the bounded, lossless JSON object carried by a say. */

package/dist/notifications.js

@@ -32,6 +32,8 @@ export async function createDefaultWakeTransport(env = process.env, suppliedTran
     }
     const { createClaudeWakeTransport } = await import('./claude-delivery.js');
     transports['claude-native'] = createClaudeWakeTransport(env);
+    const { HttpWakeTransport } = await import('./http-delivery.js');
+    transports.http = new HttpWakeTransport({ env });
     return createWakeTransport(transports);
 }
 /** Route selection only: all implementations receive the same request and final gate. */

package/dist/operation-presentation.d.ts

@@ -24,8 +24,7 @@ export declare function renderStatusResult(squarePath: string, data: StatusResul
 export declare function renderListeningResult(squarePath: string, data: ListeningResult): string | undefined;
 export type ListenerVerb = 'listen' | 'ignore' | 'unlisten';
 export declare function renderListenerChange(squarePath: string, verb: ListenerVerb, data: ListenerChangeResult): string | undefined;
-export type LifecycleVerb = 'hold' | 'resume' | 'done';
-export declare function renderLifecycleResult(squarePath: string, verb: LifecycleVerb, data: LifecycleResult): string | undefined;
+export declare function renderLifecycleResult(squarePath: string, data: LifecycleResult): string | undefined;
 /** The refusal facts a transport has after normalizing a failure, without the live error. */
 export interface FailureReport {
     readonly code: string;

package/dist/operation-presentation.js

@@ -2,7 +2,7 @@
 // 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, renderRoomChangeText, 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, } from './presentation.js';
 import { formatRelativeTime, formatTimestamp } from './time.js';
 import { style } from './tty-style.js';
 export const PARTICIPANTS_DEFAULT_LIMIT = 20;
@@ -34,7 +34,7 @@ export function renderJoinResult(data, owner) {
         ...(after.enrichmentUnavailable ? ['  · joined; recent activity and context are unavailable right now'] : []),
         ...(isRejoin || activities === '' ? [] : ['', style('dim', 'recent activity'), activities]),
         ...fallback,
-    ].join('\n'), { participantCount: after.standingCount, held: after.held });
+    ].join('\n'), { participantCount: after.standingCount });
 }
 function isGestureOnly(body) {
     return /\*[^*]*\*/.test(body) && body.replace(/\*[^*]*\*/g, '').trim() === '';
@@ -63,7 +63,7 @@ export function renderExpression(squarePath, data, owner) {
         : `\n○ ${participantIdentity(data.replyAuthorNotHere)} isn't in the square right now — the reply landed without reaching them`;
     const unmatchedNotice = data.unmatchedMentions?.length
         ? `\n  · ${data.unmatchedMentions.map((token) => `@${token} isn't standing here`).join('; ')} — ${activity.mentions.length === 0 && activity.reply === undefined ? 'activity landed bare' : 'left as literal text'}` : '';
-    return withPathOutput(projection.location ?? squarePath, confirmation + (data.hint ? `\n${style('dim', `· ${data.hint}`)}` : '') + replyNotice + unmatchedNotice + pending, { participantCount: projection.standingCount, held: projection.held });
+    return withPathOutput(projection.location ?? squarePath, confirmation + (data.hint ? `\n${style('dim', `· ${data.hint}`)}` : '') + replyNotice + unmatchedNotice + pending, { participantCount: projection.standingCount });
 }
 function continuationCommand(squarePath, name, options, owner) {
     const args = ['--now'];
@@ -83,7 +83,7 @@ export function renderCatchOutcome(squarePath, data, options = {}, owner) {
     const location = projection.location ?? squarePath;
     const name = projection.participant;
     const stop = data.reason === 'drained' && data.activities.length > 0 ? undefined : data.reason;
-    const header = { participantCount: projection.standingCount, held: projection.held };
+    const header = { participantCount: projection.standingCount };
     const statusOptions = {
         squarePath: location, name, owner, presence: projection.presence,
         showCatchHint: !projection.deliveryAvailable,
@@ -256,11 +256,6 @@ export function renderStatusResult(squarePath, data) {
         }
     }
     const cap = data.hardCap === null ? 'unlimited' : `${data.hardCap} each`;
-    const held = data.held;
-    const holdTime = held?.at === undefined ? 'just now' : formatRelativeTime(held.at, data.now);
-    const hold = held !== null
-        ? `· ${held.by === undefined ? 'someone' : participantIdentity(held.by)} raised a hand${held.reason ? ` — ${held.reason}` : ''}${style('dim', ` · ${holdTime}`)}`
-        : undefined;
     const visible = data.latestActivity === undefined
         ? { text: '', bodyClipped: false }
         : renderAmbientEventFacts(data.latestActivity, presentation.viewer, {
@@ -293,13 +288,13 @@ export function renderStatusResult(squarePath, data) {
     ].join(' · ');
     const output = [
         style('dim', counts),
-        ...(hold === undefined ? [] : ['', hold]), '', style('dim', 'around the square'), ...people, '', style('dim', 'latest'), ...latest,
+        '', style('dim', 'around the square'), ...people, '', style('dim', 'latest'), ...latest,
         ...(data.listening === undefined ? [] : [
             '', style('dim', 'you listen to'),
             ...(data.listening.length === 0 ? ['  ○ not turned toward anyone'] : data.listening.map((name) => `  · ${participantIdentity(name)}`)),
         ]),
     ].join('\n');
-    return withPathOutput(squarePath, output, { participantCount: presentation.standingCount, held: data.held !== null });
+    return withPathOutput(squarePath, output, { participantCount: presentation.standingCount });
 }
 export function renderListeningResult(squarePath, data) {
     const projection = data.observation;
@@ -308,7 +303,7 @@ export function renderListeningResult(squarePath, data) {
     const body = data.listening.length === 0
         ? `○ ${participantIdentity(projection.participant)} is not turned toward anyone`
         : ['listening', ...data.listening.map((target) => `  · ${participantIdentity(target)}`)].join('\n');
-    return withPathOutput(squarePath, body, { participantCount: projection.standingCount, held: projection.held });
+    return withPathOutput(squarePath, body, { participantCount: projection.standingCount });
 }
 export function renderListenerChange(squarePath, verb, data) {
     const projection = data.observation;
@@ -324,19 +319,16 @@ export function renderListenerChange(squarePath, verb, data) {
             : verb === 'ignore' ? `${actor} already ignores ${target} — only bells will reach you from them`
                 : `${actor} is not listening to ${target}`;
     return withPathOutput(squarePath, `${data.activity === null ? '○' : '·'} ${action}`, {
-        participantCount: projection.standingCount, held: projection.held,
+        participantCount: projection.standingCount,
     });
 }
-export function renderLifecycleResult(squarePath, verb, data) {
+export function renderLifecycleResult(squarePath, data) {
     const projection = data.observation;
     if (projection === undefined)
         return undefined;
-    const header = { participantCount: projection.standingCount, held: projection.held };
-    if (verb === 'done') {
-        return withPathOutput(projection.location ?? squarePath, `○ you stepped out — your footsteps fade · ${data.activity.id}`, header);
-    }
-    const line = `${renderRoomChangeText(data.activity)} · ${data.activity.id} · just now`;
-    return withPathOutput(projection.location ?? squarePath, verb === 'hold' ? `· ${line}` : `✓ ${line}`, header);
+    return withPathOutput(projection.location ?? squarePath, `○ you stepped out — your footsteps fade · ${data.activity.id}`, {
+        participantCount: projection.standingCount,
+    });
 }
 /** Refusal lines with the same recovery commands the CLI prints. */
 export function renderFailureLines(failure, options = {}) {

package/dist/ports.d.ts

@@ -1,4 +1,5 @@
 import type { Act, ActivityId, Owner, HardCap, Seat, StoredAct, WakeAddress, WakeRoute, WatchLease } from './model.js';
+import type { AttemptOutcome } from './delivery-attempts.js';
 import type { MetadataMatch, DeliveryDeferralFact } from './delivery-deferral.js';
 export type ActivityIndex = number;
 export interface SquareHeader {
@@ -35,7 +36,7 @@ export interface ActivityHead {
     readonly index: ActivityIndex;
     readonly at: number;
     readonly kind: StoredAct['kind'];
-    readonly actor?: string;
+    readonly actor: string;
     readonly reach?: 'bell';
     readonly reply?: ActivityIndex;
 }
@@ -47,7 +48,6 @@ export interface ActivityFilter {
     readonly kinds?: readonly StoredAct['kind'][];
     readonly actors?: readonly string[];
     readonly actorMatch?: 'identity' | 'exact';
-    readonly actorRequired?: true;
     readonly afterAt?: number;
 }
 export interface IndexPage {
@@ -71,12 +71,9 @@ export interface DirectedHead {
     readonly at: number;
     readonly actor: string;
     readonly recipient: string;
-    readonly route: 'mention' | 'reply' | 'attention' | 'bell';
-}
-export interface LandedRecipient {
-    readonly recipient: string;
-    readonly route: DirectedHead['route'];
+    readonly route: import('./attention.js').AudienceRoute;
 }
+export type LandedRecipient = import('./attention.js').AudienceRecipient;
 export interface ReceiptFacts {
     readonly latestAt?: number;
     readonly latestActorActivityIndex?: number;
@@ -109,7 +106,7 @@ export interface DeliveryEvidence {
     readonly generation: ActivityId;
     readonly activity: ActivityId;
     readonly kind: 'wake' | 'presentation';
-    readonly outcome: 'dispatching' | 'accepted' | 'failed' | 'unknown' | 'released' | 'presented' | 'clipped';
+    readonly outcome: AttemptOutcome;
     readonly attemptN: number;
     readonly at: number;
     readonly expiresAt?: number;
@@ -178,12 +175,6 @@ export interface SquareRead {
     roster(): readonly ParticipantFact[];
     attention(listener: string): readonly AttentionFact[];
     incomingAttention(sender: string): readonly AttentionFact[];
-    hold(): {
-        readonly active: boolean;
-        readonly at?: number;
-        readonly reason?: string;
-        readonly actor?: string;
-    };
     activity(index: ActivityIndex): StoredAct | undefined;
     activityHeads(filter: ActivityFilter, page: IndexPage): FactPage<ActivityHead>;
     activities(indexes: readonly ActivityIndex[]): readonly StoredAct[];

package/dist/presentation-operations.d.ts

@@ -1,22 +1,17 @@
 import type { PresentationResult, PresentPendingInput } from './ports.js';
 /** Prepare custody before any external effect. A batch prepares every included item first. */
-export declare function preparePendingPresentation(input: Omit<PresentPendingInput, 'sink'>): Promise<{
-    activity: {
-        kind: "say";
-        actor: import("./square-core.js").Participant;
-        at?: number;
-        body?: string;
-        metadata?: import("./model.js").ActivityMetadata;
-        mentions?: readonly import("./square-core.js").Participant[];
-        reach?: import("./square-core.js").Reach;
-        reply?: number;
-    } & {
-        index: number;
-        at: number;
-    };
-    eligible(): Promise<boolean>;
-    release(outcome?: "released" | "failed", message?: string): Promise<void>;
-    recordPresented(): Promise<PresentationResult>;
-} | undefined>;
-/** Eligibility precedes the sink; only captured ownership fences its truthful completion. */
+export declare function preparePendingPresentation(input: Omit<PresentPendingInput, 'sink'>): Promise<import("./delivery-effects.js").PreparedPresentation<{
+    kind: "say";
+    actor: import("./square-core.js").Participant;
+    at?: number;
+    body?: string;
+    metadata?: import("./model.js").ActivityMetadata;
+    mentions?: readonly import("./square-core.js").Participant[];
+    reach?: import("./square-core.js").Reach;
+    reply?: number;
+} & {
+    index: number;
+    at: number;
+}> | undefined>;
+/** Square sinks explicitly classify rejection as failed; the public effect core defaults to unknown. */
 export declare function presentPending(input: PresentPendingInput): Promise<PresentationResult>;

package/dist/presentation-operations.js

@@ -4,6 +4,7 @@ import { isSquareError } from './model.js';
 import { pendingHead, sameJoin } from './delivery.js';
 import { deliveryDeferralExpiry } from './delivery-deferral.js';
 import { asSeatRef } from './seats.js';
+import { preparePresentation, presentPrepared } from './delivery-effects.js';
 /** Prepare custody before any external effect. A batch prepares every included item first. */
 export async function preparePendingPresentation(input) {
     const index = typeof input.activity === 'number' ? input.activity : parseActivityId(input.activity);
@@ -30,67 +31,56 @@ export async function preparePendingPresentation(input) {
             && sameJoin(facts, participant);
     };
     const claimToken = randomUUID();
-    const claimed = await input.artifact.claimDelivery({ seat: ref, activity: formatActivityId(index), kind: 'presentation',
-        at: input.now ?? Date.now(), leaseMs: input.timeoutMs ?? 5000, claimToken }, input.signal).catch(() => ({ status: 'stale' }));
-    if (claimed.status !== 'acquired')
-        return undefined;
-    let effectObserved = false, released = false;
-    return {
-        activity: item,
-        async eligible() {
-            return (await input.artifact.read(facts => owns(facts) && input.current?.(facts) !== false
-                && pendingHead(facts, participant.name, index) !== undefined
-                && deliveryDeferralExpiry(facts, seat, index, input.now ?? Date.now()) === undefined, input.signal).catch(() => undefined))?.value === true;
-        },
-        async release(outcome = 'released', message) {
-            if (effectObserved || released)
-                return;
-            released = true;
-            await input.artifact.settleAs({ kind: 'participant', seat: ref }, facts => facts.completeDelivery({
-                seat: ref, activity: formatActivityId(index), claimToken, outcome, at: Date.now(),
-                ...(message === undefined ? {} : { message }),
-            })).catch(() => false);
+    return preparePresentation({
+        payload: item, coverage: input.markSeen === false ? 'clipped' : 'full',
+        port: {
+            async claim(signal) {
+                const claimed = await input.artifact.claimDelivery({ seat: ref, activity: formatActivityId(index), kind: 'presentation',
+                    at: input.now ?? Date.now(), leaseMs: input.timeoutMs ?? 5000, claimToken }, signal).catch(() => ({ status: 'stale' }));
+                return claimed.status === 'acquired' ? { token: claimToken, ordinal: claimed.attemptN } : undefined;
+            },
+            async current(signal) {
+                return (await input.artifact.read(facts => owns(facts) && input.current?.(facts) !== false
+                    && pendingHead(facts, participant.name, index) !== undefined
+                    && deliveryDeferralExpiry(facts, seat, index, input.now ?? Date.now()) === undefined, signal ?? input.signal)).value;
+            },
+            async settle(claim, completion) {
+                const success = completion.outcome === 'presented' || completion.outcome === 'clipped';
+                const { value } = await input.artifact.settleAs({ kind: 'participant', seat: ref }, facts => {
+                    // Captured ownership fences truth; post-effect policy/cancellation cannot veto it.
+                    if (!owns(facts))
+                        return false;
+                    if (!facts.completeDelivery({ seat: ref, activity: formatActivityId(index), claimToken: claim.token,
+                        outcome: completion.outcome, at: success ? input.now ?? Date.now() : Date.now(),
+                        ...(completion.reason === 'threw' ? { message: completion.error instanceof Error ? completion.error.message : String(completion.error) } : {}),
+                    }))
+                        return false;
+                    if (completion.outcome === 'presented')
+                        facts.markSeen(participant.name, [index], input.now ?? Date.now());
+                    return true;
+                }).catch(error => {
+                    if (!success || isSquareError(error) && error.code === 'already_joined')
+                        return { value: false };
+                    throw error;
+                });
+                return value;
+            },
         },
-        async recordPresented() {
-            // Success is an observed external fact, not another eligibility decision. Neither
-            // post-effect cancellation nor a new deferral can erase it and authorize replay.
-            effectObserved = true;
-            const outcome = input.markSeen === false ? 'clipped' : 'presented';
-            const { value: committed } = await input.artifact.settleAs({ kind: 'participant', seat: ref }, facts => {
-                if (!owns(facts))
-                    return false;
-                if (!facts.completeDelivery({ seat: ref, activity: formatActivityId(index), claimToken, outcome, at: input.now ?? Date.now() }))
-                    return false;
-                if (input.markSeen !== false)
-                    facts.markSeen(participant.name, [index], input.now ?? Date.now());
-                return true;
-            }).catch(error => {
-                if (isSquareError(error) && error.code === 'already_joined')
-                    return { value: false };
-                throw error;
-            });
-            return committed ? { presented: true, activity: item } : { presented: false };
-        },
-    };
+    }, { signal: input.signal });
 }
-/** Eligibility precedes the sink; only captured ownership fences its truthful completion. */
+/** Square sinks explicitly classify rejection as failed; the public effect core defaults to unknown. */
 export async function presentPending(input) {
     const prepared = await preparePendingPresentation(input);
     if (prepared === undefined)
         return { presented: false };
-    try {
-        if (!await prepared.eligible() || input.signal?.aborted)
-            return { presented: false };
-        try {
-            await input.sink.present(prepared.activity);
-        }
-        catch (error) {
-            await prepared.release('failed', error instanceof Error ? error.message : String(error));
-            throw error;
-        }
-        return await prepared.recordPresented();
-    }
-    finally {
-        await prepared.release();
-    }
+    const report = await presentPrepared(prepared, activity => input.sink.present(activity), {
+        signal: input.signal, classifyError: () => 'failed',
+    });
+    if (report.observation.kind === 'threw')
+        throw report.observation.error;
+    const result = report.settlements[0].result;
+    if (result.persistence.status === 'error')
+        throw result.persistence.error;
+    return report.observation.kind === 'returned' && result.persistence.status === 'recorded'
+        ? { presented: true, activity: prepared.payload } : { presented: false };
 }

package/dist/presentation.d.ts

@@ -5,7 +5,6 @@ import type { Activity, UnreadActivitySummary, ParticipantSummary } from './squa
 export type WatchStatus = 'idle' | 'drained' | 'quorum' | 'capped';
 interface HeaderOptions {
     participantCount?: number;
-    held?: boolean;
     /** Refusal bodies go to stderr, which stays literal even when it is a TTY. */
     plain?: boolean;
 }
@@ -14,7 +13,6 @@ interface ParticipantOutputOptions {
     squarePath: string;
     name: string;
     participantCount?: number;
-    held?: boolean;
 }
 interface ActivityLimitOptions extends ParticipantOutputOptions {
     count?: number;
@@ -27,17 +25,13 @@ interface ActivityBlockedOptions extends ParticipantOutputOptions {
     draftPath?: string;
 }
 interface ExpressWaitingOptions {
-    reason: 'throttled' | 'held';
+    reason: 'throttled';
     delayMs?: number;
-    holder?: string;
-    holdReason?: string;
 }
 interface ExpressNoWaitOptions extends ParticipantOutputOptions {
-    reason: 'throttled' | 'held';
+    reason: 'throttled';
     retryCommand: string;
     delayMs?: number;
-    holder?: string;
-    holdReason?: string;
     draftPath?: string;
 }
 interface WatchStatusOptions extends ParticipantOutputOptions {
@@ -56,7 +50,6 @@ export declare function withPathOutput(squarePath: string, body?: string, opts?:
 /** The same header/blank/body layout as withPathOutput, for refusal bodies written to stderr. */
 export declare function formatRefusal(squarePath: string, bodyLines: string[], opts?: {
     participantCount?: number;
-    held?: boolean;
 }): string;
 export declare function refusalText(error: unknown): string;
 export declare function quoteShell(value: string): string;