@astrosheep/square 0.3.93 → 0.3.95

package/dist/paseo-delivery.js

@@ -17,28 +17,30 @@ function diagnostic(phase, address, code) {
 }
 export class PaseoWakeTransport {
     opts;
+    discovering;
     constructor(opts = {}) {
         this.opts = opts;
     }
+    /** Coalesce overlapping inventory reads only; a later send must rediscover current status. */
+    discover(timeoutMs) {
+        return this.discovering ??= Promise.resolve().then(() => (this.opts.discover ?? discoverPaseoAgents)(timeoutMs))
+            .finally(() => { this.discovering = undefined; });
+    }
     async attempt(request, timeoutMs, beforeSend) {
         const address = request.route.address;
         const deadline = Date.now() + timeoutMs;
         const remainingMs = () => Math.max(0, deadline - Date.now());
         const budgetUnavailable = () => ({
             outcome: 'failed',
-            unavailable: true,
             signature: 'dispatch_budget_exhausted',
             message: 'The wake dispatch budget elapsed before Paseo accepted the wake.',
-            retainRoute: true,
         });
         const agentId = address.agentId?.trim();
         if (!agentId) {
             return {
                 outcome: 'failed',
-                unavailable: true,
                 signature: 'invalid_address',
                 message: 'Paseo route has no agent id.',
-                routeStale: true,
                 diagnostic: diagnostic('selection', address, 'invalid_address'),
             };
         }
@@ -49,30 +51,25 @@ export class PaseoWakeTransport {
         let remaining = remainingMs();
         if (remaining === 0)
             return budgetUnavailable();
-        const discovery = (this.opts.discover ?? discoverPaseoAgents)(remaining);
+        const discovery = await this.discover(remaining);
         if (discovery.error && discovery.agents.length === 0) {
             return {
                 outcome: 'failed',
-                unavailable: true,
                 // A credential or authorization refusal is proven; anything else may be transient.
                 signature: /password|auth|unauthori[sz]ed/i.test(discovery.error) ? 'discovery_rejected'
                     : /DAEMON_NOT_RUNNING|ECONNREFUSED|ENOENT|not found.*executable|ETIMEDOUT|timed out|timeout/i.test(discovery.error)
                         ? 'discovery_transient' : 'discovery_rejected',
                 message: `Paseo unavailable: ${discovery.error}`,
                 diagnostic: diagnostic('discovery', address, 'unavailable'),
-                retainRoute: true,
             };
         }
         const agent = discovery.agents.find((candidate) => candidate.id === agentId);
         if (agent === undefined || agent.status !== 'idle') {
             return {
                 outcome: 'failed',
-                unavailable: true,
                 signature: agent === undefined ? 'address_not_found' : 'agent_not_idle',
                 message: agent === undefined ? 'The registered Paseo agent was not found.' : 'The registered Paseo agent is not idle.',
                 diagnostic: diagnostic('selection', address, agent === undefined ? 'not_found' : 'not_idle'),
-                ...(agent === undefined ? {} : { retainRoute: true }),
-                ...(agent === undefined ? { routeStale: true } : {}),
             };
         }
         remaining = remainingMs();
@@ -81,11 +78,9 @@ export class PaseoWakeTransport {
         if (!(await (this.opts.waitForBoundary ?? waitForPaseoWakeBoundary)(agent, remaining))) {
             return {
                 outcome: 'failed',
-                unavailable: true,
                 signature: 'boundary_unavailable',
                 message: 'Paseo did not reach the current tool boundary before the wake timeout.',
                 diagnostic: diagnostic('boundary', address, 'unavailable'),
-                retainRoute: true,
             };
         }
         if (!(await beforeSend()))

package/dist/paseo-state.d.ts

@@ -7,8 +7,8 @@ export interface PaseoAgent {
 export declare function discoverPaseoAgents(timeoutMs?: number, opts?: {
     args?: string[];
     bin?: string;
-}): {
+}): Promise<{
     agents: PaseoAgent[];
     error?: string;
-};
+}>;
 export declare function waitForPaseoWakeBoundary(agent: Pick<PaseoAgent, 'id' | 'status'>, timeoutMs?: number): Promise<boolean>;

package/dist/paseo-state.js

@@ -1,11 +1,13 @@
-import { execFileSync } from 'node:child_process';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
 import { waitForPaseoToolBoundary } from './paseo-timeline.js';
-export function discoverPaseoAgents(timeoutMs = 5000, opts = {}) {
+const execFileAsync = promisify(execFile);
+export async function discoverPaseoAgents(timeoutMs = 5000, opts = {}) {
     try {
-        const raw = execFileSync(opts.bin ?? process.env.SQUARE_PASEO_BIN ?? 'paseo', [...(opts.args ?? []), 'ls', '--global', '--json'], {
+        const { stdout: raw } = await execFileAsync(opts.bin ?? process.env.SQUARE_PASEO_BIN ?? 'paseo', [...(opts.args ?? []), 'ls', '--global', '--json'], {
             encoding: 'utf8',
             timeout: timeoutMs,
-            stdio: ['ignore', 'pipe', 'pipe'],
+            maxBuffer: 1024 * 1024,
         });
         const parsed = JSON.parse(raw);
         const agents = Array.isArray(parsed) ? parsed : parsed?.agents;

package/dist/plugins/opencode/delivery.js

@@ -3,39 +3,48 @@ import { createArtifactPort } from '../../artifact.js';
 import { deliverPending } from '../../delivery-operations.js';
 import { nativePendingPreview, observeSessionPending, projectSessionSeats } from '../../inbox.js';
 import { automaticWakeEligible, presentationBlocksWake } from '../../delivery.js';
-import { sameBody } from '../../model.js';
+import { harnessOwner, decodeHarnessOwner } from '../../owner.js';
 import { formatActivityId, parseActivityId } from '../../square-core.js';
 import { indexedSquareEntries } from '../../square-index.js';
 import { asSeatRef } from '../../seats.js';
+import { restoreSessionSeats } from '../../session-lifecycle.js';
 import { presentPending } from '../../presentation-operations.js';
 import { createNativeInputId, sendNativeText } from '../../packages/agent-delivery/src/opencode-native.js';
 const routeKind = 'opencode-server';
-const bodyFor = (sessionId) => ({ channel: 'opencode', session: sessionId });
+const ownerFor = (sessionId) => harnessOwner({ channel: 'opencode', session: sessionId });
 const payloadHash = (payload) => createHash('sha256').update(payload).digest('hex');
-function preview(facts, location, seat, index) {
+function preview(facts, location, captured, index) {
+    const seat = facts.seat(captured.participant);
+    if (seat === undefined || seat.attachment !== 'attached' || seat.generation !== captured.generation || seat.owner !== captured.owner)
+        return undefined;
+    const wake = seat.wakeAddress;
+    if (wake?.kind !== routeKind)
+        return undefined;
     return nativePendingPreview(facts, {
-        location, routeKind, sessionId: seat.body.session, participant: seat.participant,
-        actIndex: index, address: { sessionId: seat.body.session }, now: Date.now(),
+        location, routeKind, generation: seat.generation, participant: seat.participant,
+        actIndex: index, address: wake.address, now: Date.now(),
     });
 }
 export async function indexedOpenCodeSessions(env) {
-    return [...new Set((await indexedSquareEntries({ channel: 'opencode' }, env)).map((entry) => entry.body.session))];
+    return [...new Set((await indexedSquareEntries({}, env)).flatMap((entry) => {
+            const coordinate = decodeHarnessOwner(entry.owner);
+            return coordinate?.channel === 'opencode' ? [coordinate.session] : [];
+        }))];
 }
 export async function discoverOpenCodeSeats(sessionId, env, signal) {
-    return projectSessionSeats({ body: bodyFor(sessionId), env }, signal);
+    return projectSessionSeats({ owner: ownerFor(sessionId), env }, signal);
 }
 function sameSeat(left, right) {
-    return left !== undefined && left.generation === right.generation && sameBody(left.body, right.body);
+    return left !== undefined && left.attachment === 'attached' && left.generation === right.generation && left.owner === right.owner;
 }
 function createOpenCodeWakeTransport(target, lifetime) {
     return {
         probe: async (route) => !lifetime.aborted && route.kind === routeKind
-            && route.sessionId === target.sessionId && route.address.sessionId === target.sessionId,
+            && route.address.sessionId === target.sessionId,
         async attempt(request, timeoutMs, beforeSend) {
             const index = parseActivityId(request.activity);
             const artifact = request.artifact;
             if (artifact === undefined || request.claimToken === undefined || index === undefined
-                || !sameBody(request.seat.body, bodyFor(target.sessionId))
                 || request.route.kind !== routeKind || request.route.address.sessionId !== target.sessionId) {
                 return { outcome: 'not-capable', diagnostic: 'OpenCode attention has no matching artifact claim or session.' };
             }
@@ -61,7 +70,7 @@ function createOpenCodeWakeTransport(target, lifetime) {
             if (result.state === 'accepted')
                 return { outcome: 'accepted' };
             if (result.state === 'unavailable')
-                return { outcome: 'failed', unavailable: true, retainRoute: true, signature: result.code };
+                return { outcome: 'failed', signature: result.code };
             return { outcome: 'unknown', signature: result.code };
         },
     };
@@ -126,7 +135,7 @@ export async function observeOpenCodeContext(sessionId, messages, env, signal) {
 }
 /** The native receiver owns no claims outside the artifact; HOME is used only for discovery. */
 export async function receiveOpenCodePending(target, env, signal) {
-    const observer = await observeSessionPending(bodyFor(target.sessionId), env);
+    const observer = await observeSessionPending(ownerFor(target.sessionId), env);
     const transport = createOpenCodeWakeTransport(target, signal);
     let waiting;
     try {
@@ -181,7 +190,8 @@ export async function receiveOpenCodePending(target, env, signal) {
 }
 /** Publish the native address into current artifact seats; the legacy route projection is not read. */
 export async function publishOpenCodeAddress(sessionId, env, signal) {
-    const seats = await discoverOpenCodeSeats(sessionId, env, signal);
+    await restoreSessionSeats(ownerFor(sessionId), env, { kind: routeKind, address: { sessionId } }, signal);
+    const seats = (await discoverOpenCodeSeats(sessionId, env, signal)).filter(({ seat }) => seat.attachment === 'attached');
     for (const { location, seat } of seats) {
         if (signal.aborted)
             return false;
@@ -199,6 +209,8 @@ export async function cancelOpenCodeDeliveries(sessionId, env, signal) {
     for (const { location, seat } of await discoverOpenCodeSeats(sessionId, env, signal)) {
         if (signal.aborted)
             return;
+        if (seat.attachment !== 'attached')
+            continue;
         const artifact = createArtifactPort(location, undefined, signal);
         try {
             const { value: through } = await artifact.read((facts) => facts.header().lastActIndex, signal);
@@ -215,9 +227,9 @@ export async function endOpenCodeSession(sessionId, env, signal) {
         if (signal.aborted)
             return;
         const { Square } = await import('../../square-api.js');
-        const square = await Square.at({ path: location, env, body: seat.body, participant: seat.participant });
+        const square = await Square.at({ path: location, env });
         try {
-            await square.endOwnedSession(seat.participant, sessionId, seat.generation, seat.body);
+            await square.endHeld(seat.participant, { owner: seat.owner, generation: seat.generation });
         }
         finally {
             await square.close();

package/dist/ports.d.ts

@@ -1,4 +1,5 @@
-import type { Act, ActivityId, Body, HardCap, Seat, StoredAct, WakeAddress, WakeRoute, WatchLease } from './model.js';
+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;
@@ -85,22 +82,22 @@ export interface ReceiptAssignment {
     readonly owner: string;
     readonly index: ActivityIndex;
 }
-export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
-    readonly [key: string]: JsonValue;
-};
-export type SeatRef = Omit<Seat, 'wakeAddress'>;
+export type SeatRef = Pick<Seat, 'participant' | 'owner' | 'generation'>;
 export type ArtifactWriteAuthority = {
     readonly kind: 'participant';
     readonly seat: SeatRef;
+} | {
+    readonly kind: 'host-cleanup';
+    readonly seat: SeatRef;
 } | {
     readonly kind: 'join';
     readonly participant: string;
-    readonly body: Body;
+    readonly owner: Owner;
     readonly wakeAddress?: WakeAddress;
 } | {
     readonly kind: 'takeover';
     readonly participant: string;
-    readonly body: Body;
+    readonly owner: Owner;
     readonly expectedGeneration: ActivityId;
     readonly wakeAddress?: WakeAddress;
 };
@@ -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;
@@ -168,9 +165,7 @@ export interface DeliveryCompletion {
 /** Domain facts exist only during a synchronous artifact callback. Values are detached. */
 export interface SquareRead {
     seat(requestedName: string): Seat | undefined;
-    seatsForBody(body: Body): readonly Seat[];
-    /** Latest completed coordinates only; never participant write authority. */
-    completedSeatsForBody(body: Body): readonly Seat[];
+    seatsForOwner(owner: Owner): readonly Seat[];
     deliveryEvidence(participant: string, generation: ActivityId, activity?: ActivityId): readonly DeliveryEvidence[];
     deliveryByToken(claimToken: string): DeliveryEvidence | undefined;
     cancelledThrough(participant: string, generation: ActivityId): number | undefined;
@@ -180,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[];
@@ -219,6 +208,10 @@ export interface SquareWrite extends SquareRead {
         readonly at: number;
     }): StoredAct;
     updateWakeAddress(seat: SeatRef, wakeAddress?: WakeAddress): boolean;
+    /** Join authority only; preserves membership and its establishing generation. */
+    reattachSeat(seat: SeatRef, wakeAddress?: WakeAddress): boolean;
+    /** Host-cleanup authority only; stale/already-detached coordinates are a no-op. */
+    detachSeat(seat: SeatRef): boolean;
     cancelThrough(seat: SeatRef, through: ActivityIndex): boolean;
     claimDelivery(input: DeliveryClaimInput): DeliveryClaimResult;
     prepareDelivery(input: DeliveryPreparation): boolean;
@@ -245,7 +238,7 @@ export interface SquareCommitResult<R> extends SquareReadResult<R> {
 /** Atomic artifact access; no framing, SQL or lazy transaction capability escapes. */
 export interface SquareArtifactPort {
     read<R>(select: (facts: SquareRead) => R, signal?: AbortSignal): Promise<SquareReadResult<R>>;
-    /** Participant/domain writes must carry an explicit authority; no body-less mutation path exists. */
+    /** Participant/domain writes must carry an explicit owner; no owner-less mutation path exists. */
     transactAs<R>(authority: ArtifactWriteAuthority, change: (facts: SquareWrite) => R, signal?: AbortSignal): Promise<SquareCommitResult<R>>;
     /** Bounded cleanup/evidence settlement on this same connection after custody was acquired.
      * Independent of request/lifetime cancellation; explicit close and authority fences still apply. */
@@ -295,28 +288,14 @@ export interface WakeRequest {
 export interface PresentationSinkPort {
     present(activity: StoredAct): void | Promise<void>;
 }
-/** Read-only presentation evidence projection for diagnostics and migration callers. */
-export interface PresentationEvidenceProjection {
-    readonly location: string;
-    readonly participant: string;
-    readonly sessionId: string;
-    readonly activity: string;
-    readonly outcome: string;
-    readonly at?: number;
-}
 export type WakeOutcome = {
     readonly outcome: 'accepted';
     readonly signature?: string;
-    readonly attemptN?: number;
 } | {
     readonly outcome: 'failed';
     readonly message?: string;
     readonly signature?: string;
     readonly diagnostic?: unknown;
-    readonly attemptN?: number;
-    readonly unavailable?: boolean;
-    readonly retainRoute?: boolean;
-    readonly routeStale?: boolean;
 } | {
     readonly outcome: 'not-capable';
     readonly diagnostic?: string;
@@ -325,15 +304,7 @@ export type WakeOutcome = {
     readonly signature?: string;
     readonly message?: string;
     readonly diagnostic?: unknown;
-    readonly attemptN?: number;
 };
-export interface DeliveryResult {
-    readonly attempted: number;
-    readonly accepted: number;
-    readonly failed: number;
-    readonly unknown: number;
-    readonly notCapable: number;
-}
 export interface DeliverPendingInput {
     readonly artifact: SquareArtifactPort;
     readonly transport: WakeTransportPort;

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

@@ -1,9 +1,10 @@
 import { randomUUID } from 'node:crypto';
 import { formatActivityId, parseActivityId } from './square-core.js';
-import { isSquareError, sameBody } from './model.js';
+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);
@@ -12,8 +13,8 @@ export async function preparePendingPresentation(input) {
     const initial = await input.artifact.read((facts) => {
         const participant = facts.participant(input.participant);
         const seat = facts.seat(input.participant);
-        if (!participant?.joined || seat === undefined || input.generation !== undefined && input.generation !== seat.generation
-            || input.seat !== undefined && (input.seat.generation !== seat.generation || !sameBody(input.seat.body, seat.body))
+        if (!participant?.joined || seat === undefined || seat.attachment !== 'attached' || input.generation !== undefined && input.generation !== seat.generation
+            || input.seat !== undefined && (input.seat.generation !== seat.generation || input.seat.owner !== seat.owner)
             || input.current?.(facts) === false || !pendingHead(facts, participant.name, index)
             || deliveryDeferralExpiry(facts, seat, index, input.now ?? Date.now()) !== undefined)
             return undefined;
@@ -26,71 +27,60 @@ export async function preparePendingPresentation(input) {
     const ref = asSeatRef(seat);
     const owns = (facts) => {
         const current = facts.seat(seat.participant);
-        return current !== undefined && sameBody(current.body, seat.body) && current.generation === seat.generation
+        return current !== undefined && current.attachment === 'attached' && current.owner === seat.owner && current.generation === seat.generation
             && 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

@@ -2,18 +2,17 @@ import { type StoredAct, type RoomChangeAct } from './model.js';
 export { participantIdentity } from './participant-identity.js';
 import { type Perception } from './square-core.js';
 import type { Activity, UnreadActivitySummary, ParticipantSummary } from './square-facade.js';
-export type WatchStatus = 'stale' | 'empty-now' | 'quorum' | 'capped';
+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;
 }
 interface ParticipantOutputOptions {
+    owner?: string;
     squarePath: string;
     name: string;
     participantCount?: number;
-    held?: boolean;
 }
 interface ActivityLimitOptions extends ParticipantOutputOptions {
     count?: number;
@@ -26,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 {
@@ -55,16 +50,15 @@ 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;
 export declare function commandPrefix(squarePath: string): string;
-export declare function participantCommandPrefix(squarePath: string, name: string): string;
+export declare function participantCommandPrefix(squarePath: string, name: string, owner?: string): string;
 /** Blocked actions end with a full copy-pasteable recovery command. */
-export declare function joinRecoveryCommand(squarePath: string, name: string): string;
+export declare function joinRecoveryCommand(squarePath: string, name: string, owner?: string): string;
 /** Taking a name is an explicit recovery choice, never an automatic retry. */
-export declare function takeoverRecoveryLines(squarePath: string, name: string): string[];
+export declare function takeoverRecoveryLines(squarePath: string, name: string, owner?: string): string[];
 export declare function participantsRecoveryCommand(squarePath: string): string;
 export declare function renderPresenceLines(recent: readonly ParticipantSummary[], now: number, limit?: number): string[];
 export declare function truncateChars(body: string, maxChars: number): {
@@ -81,14 +75,12 @@ interface RenderedEvent {
 export declare function renderEventCli(event: StoredAct | Activity, opts?: {
     now?: number;
     preview?: number;
-    actNumber?: number;
     mention?: string;
 }): string;
 export declare function renderAmbientEventFacts(event: StoredAct | Activity, viewer: string, opts?: {
     now?: number;
     preview?: number;
     presencePreview?: number;
-    actNumber?: number;
     mention?: string;
     perception?: Perception;
 }): RenderedEvent;
@@ -96,11 +88,9 @@ export declare function renderAmbientEvent(event: StoredAct | Activity, viewer:
     now?: number;
     preview?: number;
     presencePreview?: number;
-    actNumber?: number;
     mention?: string;
     perception?: Perception;
 }): string;
-export declare function renderPendingFeed(publicItems: readonly StoredAct[], sayNumbers: Readonly<Record<number, number>>, perceptions: Readonly<Record<number, Perception>>, viewer: string): string;
 export declare function renderActivityBlocked(opts: ActivityBlockedOptions): string;
 /** An indeterminate or already-committed send only points to inspection, never resend. */
 export declare function renderActivityUncertain(opts: ParticipantOutputOptions & {