@astrosheep/square 0.4.6 → 0.4.8

package/dist/notifications.js

@@ -1,52 +1,50 @@
 import { createDefaultDeliveryTransports } from './wake-transports.js';
 export { createDefaultDeliveryTransports } from './wake-transports.js';
-function deliveryWaitMs(env = process.env) {
-    const configured = Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000);
-    return Number.isSafeInteger(configured) && configured > 0 ? configured : 5000;
-}
+const DEFAULT_DELIVERY_WAIT_MS = 5000;
+const NATIVE_RECEIVER_ROUTES = new Set(['codex-queue', 'claude-mod', 'pi-native']);
 /** Best-effort dispatch for currently eligible cards, including cards restored by release. */
 export async function dispatchEligibleCards(ledger, owner, options = {}) {
-    options = { ...options, signal: options.signal ?? AbortSignal.timeout(deliveryWaitMs(options.env)) };
-    const session = await ledger.session(owner, options.signal);
-    if (!session || session.state !== 'attached' || options.signal?.aborted)
+    const signal = options.signal ?? AbortSignal.timeout(DEFAULT_DELIVERY_WAIT_MS);
+    const session = await ledger.session(owner, signal);
+    if (!session || session.state !== 'attached' || signal.aborted)
         return;
-    const pending = await ledger.pending(owner, { generation: session.generation }, options.signal);
+    const pending = await ledger.pending(owner, { generation: session.generation }, signal);
     for (const card of pending)
-        await dispatchPostedCard(ledger, owner, card.key, options.track ?? (() => undefined), options.env, options.signal, options.transports);
+        await dispatchPostedCard(ledger, owner, card.key, options.track ?? (() => undefined), signal, options.transports);
 }
 /** Post, then best-effort dispatch without consulting producer storage. */
 export async function postAndDispatch(ledger, input, options = {}) {
-    options = { ...options, signal: options.signal ?? AbortSignal.timeout(deliveryWaitMs(options.env)) };
-    const result = await ledger.post(input, options.signal);
+    const signal = options.signal ?? AbortSignal.timeout(DEFAULT_DELIVERY_WAIT_MS);
+    const result = await ledger.post(input, signal);
     if (result.status === 'posted' || result.status === 'duplicate') {
         try {
-            await dispatchEligibleCards(ledger, input.owner, options);
+            await dispatchEligibleCards(ledger, input.owner, { ...options, signal });
         }
         catch { /* Posting is already committed. */ }
     }
     return result;
 }
 /** Best-effort dispatch after a card has been posted; never inspect producer storage. */
-export async function dispatchPostedCard(ledger, owner, key, track, env = process.env, signal, suppliedTransports) {
+export async function dispatchPostedCard(ledger, owner, key, track, signal, suppliedTransports) {
     if (signal?.aborted)
         return;
-    const timeoutMs = deliveryWaitMs(env);
-    signal ??= AbortSignal.timeout(timeoutMs);
+    signal ??= AbortSignal.timeout(DEFAULT_DELIVERY_WAIT_MS);
     const session = await ledger.session(owner, signal);
     if (!session || session.state !== 'attached')
         return;
-    const transports = suppliedTransports ?? await createDefaultDeliveryTransports(env);
-    for (const route of session.routes) {
-        // Claude and Codex custody belongs to their native receivers, including for
-        // callers that supply transports explicitly to the producer API.
-        if (['codex-queue', 'claude-async-hook', 'claude-native'].includes(route.kind))
-            continue;
-        if (signal?.aborted)
+    // Native receiver custody belongs to the receiver itself, including for
+    // callers that supply transports explicitly to the producer API.
+    const routes = session.routes.filter(route => !NATIVE_RECEIVER_ROUTES.has(route.kind));
+    if (!routes.length)
+        return;
+    const transports = suppliedTransports ?? await createDefaultDeliveryTransports();
+    for (const route of routes) {
+        if (signal.aborted)
             return;
         const transport = transports.find(candidate => candidate.kind === route.kind);
         if (!transport)
             continue;
-        const result = await ledger.dispatchHandoff(owner, key, transport, { generation: session.generation, timeoutMs, signal });
+        const result = await ledger.dispatchHandoff(owner, key, transport, { generation: session.generation, timeoutMs: DEFAULT_DELIVERY_WAIT_MS, signal });
         track(result);
         if (result.outcome === 'accepted' || result.outcome === 'presented' || result.outcome === 'unknown')
             return;

package/dist/operation-control.d.ts

@@ -1,4 +1,3 @@
 import type { OperationControl, OperationFailureDetail } from './neutral.js';
 export declare function checkControl(control?: OperationControl): void;
-export declare function squareClock(env: NodeJS.ProcessEnv, clock?: () => number): () => number;
 export declare function failure(error: unknown, detail: OperationFailureDetail): Error;

package/dist/operation-control.js

@@ -1,18 +1,7 @@
-import { SquareError } from './neutral.js';
 export function checkControl(control) {
     if (control?.signal?.aborted)
         throw control.signal.reason ?? new Error('Square operation was cancelled');
 }
-export function squareClock(env, clock) {
-    if (clock !== undefined)
-        return clock;
-    if (env.SQUARE_NOW_MS === undefined)
-        return Date.now;
-    const value = Number.parseInt(env.SQUARE_NOW_MS, 10);
-    if (!Number.isFinite(value))
-        throw new SquareError('invalid_args', 'Invalid SQUARE_NOW_MS: expected integer milliseconds.');
-    return () => value;
-}
 export function failure(error, detail) {
     const normalized = error instanceof Error ? error : new Error(String(error), { cause: error });
     Object.assign(normalized, { operation: detail });

package/dist/operation-presentation.d.ts

@@ -1,32 +1,34 @@
-import type { PerceiveOptions, PerceiveResult, ExpressResult, HistoryQuery, HistoryResult, JoinResult, LifecycleResult, ListenerChangeResult, ListeningResult, OperationFailureDetail, ParticipantsResult, StatusResult, DiscoveryResult } from './square-facade.js';
+import type { PerceiveOptions, PerceiveResult, ExpressResult, HistoryQuery, HistoryResult, JoinResult, LifecycleResult, ListenerChangeResult, OperationFailureDetail, SquareErrorFacts, StatusResult, DiscoveryResult } from './square-facade.js';
+import { type PresentationSurface } from './presentation.js';
 export declare function renderSquareList(data: DiscoveryResult, projection: {
     now: number;
     depth: number;
     limit: number;
+    surface?: PresentationSurface;
 }): string;
-export declare const PARTICIPANTS_DEFAULT_LIMIT = 20;
-export declare const PARTICIPANTS_MAX_LIMIT = 100;
 /** A join receipt whose participant is already reduced to its serializable name. */
 export type JoinPresentation = Omit<JoinResult, 'participant'> & {
     readonly participant: {
         readonly name: string;
     } | string;
 };
-export declare function renderJoinResult(data: JoinPresentation, owner?: string): string | undefined;
-export declare function renderExpression(squarePath: string, data: ExpressResult, owner?: string): string | undefined;
+export declare function renderJoinResult(data: JoinPresentation, owner?: string, surface?: PresentationSurface): string | undefined;
+export declare function renderExpression(squarePath: string, data: ExpressResult, owner?: string, surface?: PresentationSurface): string | undefined;
 /** Render settled perceive facts; no selection, terminal decisions, receipts or wait machinery. */
-export declare function renderPerceiveOutcome(squarePath: string, data: PerceiveResult, options?: PerceiveOptions, owner?: string): {
+export declare function renderPerceiveOutcome(squarePath: string, data: PerceiveResult, options?: PerceiveOptions, owner?: string, surface?: PresentationSurface): {
     stdout: string;
     exitCode: number;
 };
+export declare function historyContinuationCommand(squarePath: string, args: readonly string[]): string;
 export declare function renderHistoryResult(squarePath: string, data: HistoryResult, options?: {
     query?: HistoryQuery;
-    noTruncate?: boolean;
+    full?: boolean;
     continuationArgs?: readonly string[];
+    surface?: PresentationSurface;
+}): string | undefined;
+export declare function renderStatusResult(squarePath: string, data: StatusResult, options?: {
+    surface?: PresentationSurface;
 }): string | undefined;
-export declare function renderParticipantsResult(squarePath: string, data: ParticipantsResult, limit?: number): string | undefined;
-export declare function renderStatusResult(squarePath: string, data: StatusResult): string | undefined;
-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 declare function renderLifecycleResult(squarePath: string, data: LifecycleResult): string | undefined;
@@ -34,16 +36,21 @@ export declare function renderLifecycleResult(squarePath: string, data: Lifecycl
 export interface FailureReport {
     readonly code: string;
     readonly message: string;
-    readonly facts?: {
-        readonly reason?: 'never_joined' | 'not_standing' | 'bell_mention_conflict' | 'not_addressed' | 'invalid_reply' | 'invalid_done_body' | 'needs_seat';
-        readonly activityId?: string;
-        readonly activityExists?: boolean;
-    };
+    readonly facts?: SquareErrorFacts;
     readonly operation?: OperationFailureDetail;
 }
-/** Refusal lines with the same recovery commands the CLI prints. */
-export declare function renderFailureLines(failure: FailureReport, options?: {
-    squarePath?: string;
-    name?: string;
-    owner?: string;
-}): string[];
+interface FailureOptions {
+    readonly squarePath?: string;
+    readonly name?: string;
+    readonly owner?: string;
+    readonly surface?: PresentationSurface;
+    readonly reply?: string;
+    /** CLI only: the saved draft and the full command that resends it. */
+    readonly draftPath?: string;
+    readonly retry?: string;
+}
+/** Express gates are physics, not mistakes: one scene for every surface, then that surface's next action. */
+export declare function isExpressGate(code: string): boolean;
+/** Refusal lines with surface-specific recovery actions. */
+export declare function renderFailureLines(failure: FailureReport, options?: FailureOptions): string[];
+export {};

package/dist/operation-presentation.js

@@ -1,9 +1,8 @@
-// Human-facing text for one settled operation. The CLI and the MCP transport both
-// render through these functions, so a person sees the same square either way.
+// Human-facing scenes for settled operations, with surface-specific next actions.
 import { sameName } from './model.js';
 import { formatActivityId } from './square-core.js';
-import { commandPrefix, joinRecoveryCommand, participantCommandPrefix, participantIdentity, participantsRecoveryCommand, quoteShell, renderAmbientEvent, renderAmbientEventFacts, renderEventCli, renderGrepActivitiesView, renderPresenceAnchor, renderWatchAlreadyActive, renderWatchReplaced, renderWatchStatus, takeoverRecoveryLines, withPathOutput, truncateChars, } from './presentation.js';
-import { formatRelativeTime, formatTimestamp } from './time.js';
+import { displayPath, formatToolAction, commandPrefix, joinRecoveryCommand, participantCommandPrefix, participantIdentity, quoteShell, renderAmbientEvent, renderAmbientEventFacts, renderEventCli, renderGrepActivitiesView, renderPresenceAnchor, renderWatchAlreadyActive, renderWatchReplaced, renderWatchStatus, renderUnreadSummary, takeoverRecoveryLines, withPathOutput, truncateChars, } from './presentation.js';
+import { formatDuration, formatRelativeTime, formatTimestamp } from './time.js';
 import { style } from './tty-style.js';
 function listDisplay(value) {
     const truncated = truncateChars(value, 159);
@@ -37,16 +36,14 @@ export function renderSquareList(data, projection) {
     if (remaining > 0) {
         lines.push(style('dim', stopped ? '  … more squares' : `  … ${remaining} more ${remaining === 1 ? 'square' : 'squares'}`));
         if (next !== undefined)
-            lines.push(`square list --depth ${projection.depth} --limit ${projection.limit} --after ${quoteShell(next)}`);
+            lines.push(projection.surface === 'tool' ? formatToolAction('list', { depth: projection.depth, limit: projection.limit, after: next }) : `square list --depth ${projection.depth} --limit ${projection.limit} --after ${quoteShell(next)}`);
     }
     if (stopped)
         lines.push(style('dim', '○ the walk stopped early — deeper squares may still be hiding'));
     return lines.join('\n') + '\n';
 }
-export const PARTICIPANTS_DEFAULT_LIMIT = 20;
-export const PARTICIPANTS_MAX_LIMIT = 100;
 const STATUS_PARTICIPANT_PREVIEW_LIMIT = 10;
-export function renderJoinResult(data, owner) {
+export function renderJoinResult(data, owner, surface = 'cli') {
     const after = data.observation;
     if (after === undefined)
         return undefined;
@@ -56,7 +53,7 @@ export function renderJoinResult(data, owner) {
         now: after.now, preview: 200, perception: event.perception,
     })).filter(Boolean).join('\n\n');
     const fallback = after.deliveryAvailable ? ['', '· when someone calls you, you’ll hear them here'] : [
-        '', `${participantCommandPrefix(after.location, name, owner)} perceive --idle 30m`,
+        '', surface === 'tool' ? formatToolAction('perceive', { location: displayPath(after.location), as: name, idle: '30m' }) : `${participantCommandPrefix(after.location, name, owner)} perceive --idle 30m`,
         '  · stay within earshot — keep this perceive open for new activity',
     ];
     const entryLine = data.kind === 'joined' ? '● you stepped into the square'
@@ -77,7 +74,7 @@ export function renderJoinResult(data, owner) {
 function isGestureOnly(body) {
     return /\*[^*]*\*/.test(body) && body.replace(/\*[^*]*\*/g, '').trim() === '';
 }
-export function renderExpression(squarePath, data, owner) {
+export function renderExpression(squarePath, data, owner, surface = 'cli') {
     const projection = data.observation;
     if (projection === undefined)
         return undefined;
@@ -87,7 +84,7 @@ export function renderExpression(squarePath, data, owner) {
         'Unread context · preview only, not consumed',
         ...context.activities.map(item => `· ${participantIdentity(item.actor)} · ${item.id}\n  ${item.preview}${item.truncated ? '… (truncated)' : ''}`),
         ...(context.remaining === 0 ? [] : [`· ${context.remaining} more unread activities`]),
-        `${participantCommandPrefix(projection.location, name, owner)} perceive`,
+        surface === 'tool' ? formatToolAction('perceive', { location: displayPath(projection.location), as: name }) : `${participantCommandPrefix(projection.location, name, owner)} perceive`,
     ].join('\n');
     const ownCount = projection.ownActivityCount;
     const capCount = projection.hardCap === null ? '' : ` · ${ownCount}/${projection.hardCap}`;
@@ -104,17 +101,17 @@ export function renderExpression(squarePath, data, owner) {
     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'];
+    const args = [];
     if (options.from?.length)
         args.push('--from', options.from.join(','));
     if (options.mention)
         args.push('--mention');
     if (options.limit !== undefined)
         args.push('--limit', String(options.limit));
-    return `${participantCommandPrefix(squarePath, name, owner)} perceive ${args.join(' ')}`;
+    return [participantCommandPrefix(squarePath, name, owner), 'perceive', ...args].join(' ');
 }
 /** Render settled perceive facts; no selection, terminal decisions, receipts or wait machinery. */
-export function renderPerceiveOutcome(squarePath, data, options = {}, owner) {
+export function renderPerceiveOutcome(squarePath, data, options = {}, owner, surface = 'cli') {
     const projection = data.observation;
     if (projection === undefined)
         return { stdout: '', exitCode: 0 };
@@ -123,7 +120,7 @@ export function renderPerceiveOutcome(squarePath, data, options = {}, owner) {
     const stop = data.reason === 'drained' && data.activities.length > 0 ? undefined : data.reason;
     const header = { participantCount: projection.standingCount };
     const statusOptions = {
-        squarePath: location, name, owner, presence: projection.presence,
+        squarePath: location, name, owner, surface, presence: projection.presence,
         showPerceiveHint: !projection.deliveryAvailable,
         ownActivityCount: projection.ownActivityCount, hardCap: projection.hardCap,
     };
@@ -138,27 +135,27 @@ export function renderPerceiveOutcome(squarePath, data, options = {}, owner) {
         now: projection.now, perception: activity.perception, mention: options.mention ? name : undefined,
     })).filter(Boolean).join('\n\n');
     const remaining = data.remaining === 0 ? ''
-        : `· ${data.remaining} matching ${data.remaining === 1 ? 'activity remains' : 'activities remain'}\n${continuationCommand(location, name, options, owner)}`;
+        : `· ${data.remaining} matching ${data.remaining === 1 ? 'activity remains' : 'activities remain'}\n${surface === 'tool' ? formatToolAction('perceive', { location: displayPath(location), as: name, ...(options.from?.length ? { from: options.from } : {}), ...(options.mention ? { mention: true } : {}), ...(options.limit !== undefined ? { limit: options.limit } : {}) }) : continuationCommand(location, name, options, owner)}`;
     const terminal = stop === undefined ? '' : renderWatchStatus({
         ...statusOptions, status: stop,
         ...(stop === 'idle' && options.idle !== undefined ? { idleMs: options.idle } : {}),
     });
     const fallback = stop === undefined && !projection.deliveryAvailable && data.remaining === 0
-        ? `${participantCommandPrefix(location, name, owner)} perceive --idle 30m\n  stay available for new activity` : '';
+        ? `${surface === 'tool' ? formatToolAction('perceive', { location: displayPath(location), as: name, idle: '30m' }) : `${participantCommandPrefix(location, name, owner)} perceive --idle 30m`}\n  stay available for new activity` : '';
     const hint = data.hint === undefined ? '' : style('dim', `· ${data.hint}`);
     return {
         stdout: withPathOutput(location, [terminal, rendered, hint, remaining, fallback].filter(Boolean).join('\n\n'), header),
         exitCode: stop === 'capped' ? 1 : 0,
     };
 }
-function renderHistoryProjection(projection, visible, noTruncate, squarePath) {
+function renderHistoryProjection(projection, visible, full, squarePath, surface) {
     const shown = visible;
-    const preview = noTruncate || shown.length <= 1 ? undefined : 200;
+    const preview = full || shown.length <= 1 ? undefined : 200;
     const chunks = [];
     // Presence anchors collect into one closing line instead of interrupting the page.
     const anchored = [];
     for (const activity of shown) {
-        const rendered = renderEventCli(activity, { preview });
+        const rendered = renderEventCli(activity, { now: projection.now, preview });
         if (rendered !== '')
             chunks.push(rendered);
         for (const participant of projection.presenceAnchors[activity.index] ?? []) {
@@ -169,13 +166,14 @@ function renderHistoryProjection(projection, visible, noTruncate, squarePath) {
     if (chunks.length === 0)
         return '○ no activity matches this history query';
     if (preview !== undefined && shown.some((activity) => activity.kind === 'say' && (activity.body?.length ?? 0) > preview)) {
-        chunks.push(`${commandPrefix(squarePath)} history --at ${shown.map((activity) => formatActivityId(activity.index)).join(',')} --no-truncate`);
+        const ids = shown.map((activity) => formatActivityId(activity.index));
+        chunks.push(surface === 'tool' ? formatToolAction('history', { location: displayPath(squarePath), at: ids, full: true }) : `${commandPrefix(squarePath)} history --at ${ids.join(',')} --full`);
     }
     if (anchored.length > 0)
         chunks.push(renderPresenceAnchor(anchored));
     return chunks.join('\n\n');
 }
-function historyContinuationCommand(squarePath, args) {
+export function historyContinuationCommand(squarePath, args) {
     return `${commandPrefix(squarePath)} history ${args.map((arg) => arg.startsWith('-') || /^act\/\d+$/.test(arg) || /^\d+$/.test(arg) ? arg : quoteShell(arg)).join(' ')}`;
 }
 /** The same query spelled as CLI arguments, for a continuation someone can actually run. */
@@ -187,14 +185,15 @@ function historyQueryArgs(query) {
         args.push('--since', formatTimestamp(query.since));
     if (query.at?.length)
         args.push('--at', query.at.join(','));
-    if (query.contextBefore !== undefined)
-        args.push('-B', String(query.contextBefore));
-    if (query.contextAfter !== undefined)
-        args.push('-A', String(query.contextAfter));
+    if (query.context !== undefined)
+        args.push('-C', String(query.context));
     if (query.mention !== undefined)
         args.push('--mention', query.mention);
-    if (query.search !== undefined)
-        args.push(query.search.mode === 'regex' ? '--grep' : '--fixed', query.search.text);
+    if (query.search !== undefined) {
+        args.push('--search', query.search.text);
+        if (query.search.mode === 'regex')
+            args.push('--regex');
+    }
     if (query.order !== undefined)
         args.push('--order', query.order);
     return args;
@@ -204,44 +203,17 @@ export function renderHistoryResult(squarePath, data, options = {}) {
     if (projection === undefined)
         return undefined;
     const query = options.query ?? {};
-    const noTruncate = options.noTruncate === true;
+    const full = options.full === true;
     const search = query.search;
     const output = search === undefined
-        ? renderHistoryProjection(projection, projection.visibleActivities, noTruncate, squarePath)
-        : renderGrepActivitiesView(projection.visibleActivities, projection.totalMatches, noTruncate, squarePath, search.text, search.mode === 'literal', () => 'full');
+        ? renderHistoryProjection(projection, projection.visibleActivities, full, squarePath, options.surface ?? 'cli')
+        : renderGrepActivitiesView(projection.visibleActivities, projection.totalMatches, full, squarePath, search.text, search.mode === 'literal', () => 'full', options.surface);
     const next = projection.continuation;
-    const base = options.continuationArgs ?? historyQueryArgs(query);
-    const continuation = next === undefined ? '' : `\n\n${historyContinuationCommand(squarePath, [...base, `--${next.direction}`, next.cursor, '--limit', String(next.limit)])}`;
+    const base = options.continuationArgs ?? [...historyQueryArgs(query), ...(full ? ['--full'] : [])];
+    const continuation = next === undefined ? '' : `\n\n${options.surface === 'tool' ? formatToolAction('history', { location: displayPath(squarePath), ...(query.from?.length ? { from: query.from } : {}), ...(query.since !== undefined ? { since: formatTimestamp(query.since) } : {}), ...(query.at?.length ? { at: query.at } : {}), ...(query.context !== undefined ? { context: query.context } : {}), ...(query.mention !== undefined ? { mention: query.mention } : {}), ...(query.search !== undefined ? { search: query.search.text, ...(query.search.mode === 'regex' ? { regex: true } : {}) } : {}), ...(query.order !== undefined ? { order: query.order } : {}), ...(full ? { full: true } : {}), [next.direction]: next.cursor, limit: next.limit }) : historyContinuationCommand(squarePath, [...base, `--${next.direction}`, next.cursor, '--limit', String(next.limit)])}`;
     return withPathOutput(squarePath, output + continuation, { participantCount: projection.standingCount });
 }
-function participantsLimitCommand(squarePath, limit) {
-    return `${commandPrefix(squarePath)} participants --limit ${limit}`;
-}
-export function renderParticipantsResult(squarePath, data, limit = PARTICIPANTS_DEFAULT_LIMIT) {
-    const projection = data.observation;
-    if (projection === undefined)
-        return undefined;
-    const now = projection.now;
-    const participants = data.participants;
-    const lines = participants.slice(0, limit).map((participant) => {
-        const glyph = participant.presence === 'done' ? '○' : participant.presence === 'watching' ? '◎' : participant.activityCount > 0 && projection.classificationByName[participant.name] === 'here' ? '●' : '○';
-        const state = participant.presence === 'watching' ? 'perceiving' : participant.presence === 'never-joined' ? 'not joined' : participant.presence;
-        const last = participant.lastActiveAt === undefined ? '—' : formatRelativeTime(participant.lastActiveAt, now);
-        return `  ${glyph} ${participant.name}${style('dim', ` · ${state} · ${participant.activityCount} ${participant.activityCount === 1 ? 'activity' : 'activities'} · ${last}`)}`;
-    });
-    const tail = participants.length <= limit
-        ? []
-        : [
-            style('dim', `  · ${lines.length} of ${participants.length} participants shown`),
-            ...(participants.length <= PARTICIPANTS_MAX_LIMIT ? [
-                `${participantsLimitCommand(squarePath, participants.length)}`,
-            ] : []),
-        ];
-    return withPathOutput(squarePath, ['participants', ...lines, ...tail].join('\n'), {
-        participantCount: projection.standingCount,
-    });
-}
-export function renderStatusResult(squarePath, data) {
+export function renderStatusResult(squarePath, data, options = {}) {
     const presentation = data.observation;
     if (presentation === undefined)
         return undefined;
@@ -278,18 +250,11 @@ export function renderStatusResult(squarePath, data) {
         people.push(...away.slice(0, STATUS_PARTICIPANT_PREVIEW_LIMIT).map(participant => `  ○ ${participantIdentity(participant.name)}${style('dim', ' · away')}`));
         if (away.length > STATUS_PARTICIPANT_PREVIEW_LIMIT)
             people.push(`  ○ … ${away.length - STATUS_PARTICIPANT_PREVIEW_LIMIT} more away`);
-        const unshown = Math.max(0, orderedHere.length - STATUS_PARTICIPANT_PREVIEW_LIMIT)
-            + Math.max(0, away.length - STATUS_PARTICIPANT_PREVIEW_LIMIT) + lingering;
         if (orderedHere.length > STATUS_PARTICIPANT_PREVIEW_LIMIT) {
             people.push(`  ○ … ${orderedHere.length - STATUS_PARTICIPANT_PREVIEW_LIMIT} more here`);
         }
         if (lingering > 0)
             people.push(`  ○ … ${lingering} lingering`);
-        if (unshown > 0) {
-            people.push(`${presentation.knownParticipantCount <= PARTICIPANTS_MAX_LIMIT
-                ? participantsLimitCommand(squarePath, presentation.knownParticipantCount)
-                : `${commandPrefix(squarePath)} participants`}`);
-        }
     }
     const cap = data.hardCap === null ? 'unlimited' : `${data.hardCap} each`;
     const visible = data.latestActivity === undefined
@@ -312,7 +277,7 @@ export function renderStatusResult(squarePath, data) {
     if (presentation.joinCount > 3)
         latest.push(style('dim', `  → … ${presentation.joinCount - 3} more stepped in`));
     if (visible.bodyClipped && data.latestActivity !== undefined) {
-        latest.push(`${commandPrefix(squarePath)} history --at ${data.latestActivity.id} -C 2 --no-truncate`);
+        latest.push(options.surface === 'tool' ? formatToolAction('history', { location: displayPath(squarePath), at: [data.latestActivity.id], context: 2, full: true }) : `${commandPrefix(squarePath)} history --at ${data.latestActivity.id} -C 2 --full`);
     }
     const counts = [
         `${orderedHere.length} here`,
@@ -332,15 +297,6 @@ export function renderStatusResult(squarePath, data) {
     ].join('\n');
     return withPathOutput(squarePath, output, { participantCount: presentation.standingCount });
 }
-export function renderListeningResult(squarePath, data) {
-    const projection = data.observation;
-    if (projection?.participant === undefined)
-        return undefined;
-    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 });
-}
 export function renderListenerChange(squarePath, verb, data) {
     const projection = data.observation;
     if (projection?.participant === undefined)
@@ -366,34 +322,81 @@ export function renderLifecycleResult(squarePath, data) {
         participantCount: projection.standingCount,
     });
 }
-/** Refusal lines with the same recovery commands the CLI prints. */
+/** Express gates are physics, not mistakes: one scene for every surface, then that surface's next action. */
+export function isExpressGate(code) {
+    return code === 'behind' || code === 'capped' || code === 'throttled' || code === 'bell_quota';
+}
+function expressGateLines(failure, options) {
+    if (!isExpressGate(failure.code))
+        return undefined;
+    const { squarePath, name, owner } = options;
+    const facts = failure.facts;
+    const tool = options.surface === 'tool';
+    const scene = failure.code === 'behind'
+        ? ['✕ your words stay unsent — someone spoke while you were away', ...renderUnreadSummary(facts?.activitySummaries ?? [])]
+        : failure.code === 'capped'
+            ? [`✕ you’ve reached your speaking cap${facts?.spoken !== undefined && facts.hardCap !== undefined ? ` — ${facts.spoken}/${facts.hardCap} spoken` : ''}`]
+            : failure.code === 'throttled'
+                ? ['✕ the square is packed — shoulder to shoulder', `  · a lull opens in ${formatDuration(facts?.retryAfterMs ?? 1)}`]
+                : ['✕ the bell stays quiet for now', `  · you can ring it again in ${formatDuration(facts?.retryAfterMs ?? 1)}`];
+    const lines = [...scene, ...(options.draftPath === undefined ? [] : [style('dim', `· draft kept: ${options.draftPath}`)])];
+    if (squarePath === undefined || name === undefined)
+        return lines;
+    const action = (verb) => tool
+        ? formatToolAction(verb, { location: displayPath(squarePath), as: name })
+        : `${participantCommandPrefix(squarePath, name, owner)} ${verb}`;
+    if (failure.code === 'behind')
+        lines.push(...(tool ? ['Take it in, then express again:', action('perceive')] : [action('perceive'), '  · take it in, then retry:']));
+    if (failure.code === 'capped')
+        lines.push('  · your words stay unsent; done only steps out', action('done'));
+    if (failure.code === 'bell_quota' && !tool)
+        lines.push('  · retry when the bell is ready:');
+    if (failure.code !== 'capped' && options.retry !== undefined)
+        lines.push(options.retry);
+    return lines;
+}
+/** Refusal lines with surface-specific recovery actions. */
 export function renderFailureLines(failure, options = {}) {
     const { squarePath, name, owner } = options;
     const facts = failure.facts;
     const reason = facts?.reason;
+    const gate = expressGateLines(failure, options);
+    if (gate !== undefined)
+        return gate;
     const marked = reason === 'never_joined' || reason === 'not_standing';
     const lines = marked ? failure.message.split('\n').map((line) => `✕ ${line}`) : [failure.message];
-    if (reason === 'needs_seat' && squarePath !== undefined && name !== undefined) {
+    if (reason === 'bell_mention_conflict' || reason === 'invalid_reply') {
+        lines[0] = reason === 'bell_mention_conflict' ? '✕ a bell cannot be combined with a mention'
+            : `Invalid ${options.surface === 'tool' ? 'reply' : '--reply'}: ${facts?.activityExists === false ? `${facts.activityId ?? options.reply ?? 'that activity'} is not in this square's history` : 'expected an activity id like act/12'}`;
+        if (squarePath !== undefined)
+            lines.push(options.surface === 'tool'
+                ? formatToolAction(reason === 'invalid_reply' ? 'history' : 'status', { location: displayPath(squarePath), ...(reason === 'invalid_reply' ? { limit: 10 } : {}) })
+                : reason === 'invalid_reply' ? `${commandPrefix(squarePath)} history --limit 10` : `${commandPrefix(squarePath)} status`);
+    }
+    else if (reason === 'needs_seat' && squarePath !== undefined && name !== undefined) {
         lines.splice(0, 1, `✕ ${failure.message}`);
-        lines.push(joinRecoveryCommand(squarePath, name, owner));
+        lines.push(options.surface === 'tool' ? formatToolAction('join', { location: displayPath(squarePath), as: name }) : joinRecoveryCommand(squarePath, name, owner));
     }
     else if (squarePath !== undefined && name !== undefined && failure.code === 'already_joined') {
         lines.splice(0, 1, `✕ ${participantIdentity(name)} shoos you out of the square`, `  · ${participantIdentity(name)} already stands here — another session holds the name`);
-        lines.push(...takeoverRecoveryLines(squarePath, name, owner));
+        lines.push(...(options.surface === 'tool' ? ['If this is your name to reclaim, takeover banishes the one standing here so you can step in:', formatToolAction('join', { location: displayPath(squarePath), as: name, takeover: true })] : takeoverRecoveryLines(squarePath, name, owner)));
+    }
+    else if (squarePath !== undefined && name !== undefined && (failure.code === 'unknown_participant' || failure.code === 'not_joined') && reason !== 'not_standing') {
+        lines.push(options.surface === 'tool' ? formatToolAction('join', { location: displayPath(squarePath), as: name }) : joinRecoveryCommand(squarePath, name, owner));
     }
     else if (squarePath !== undefined && reason === 'never_joined') {
-        lines.push(failure.operation?.subject !== 'filter' && name !== undefined
-            ? joinRecoveryCommand(squarePath, name, owner) : participantsRecoveryCommand(squarePath));
+        lines.push(options.surface === 'tool' ? (failure.operation?.subject !== 'filter' && name !== undefined ? formatToolAction('join', { location: displayPath(squarePath), as: name }) : formatToolAction('status', { location: displayPath(squarePath) })) : failure.operation?.subject !== 'filter' && name !== undefined
+            ? joinRecoveryCommand(squarePath, name, owner) : `${commandPrefix(squarePath)} status`);
     }
     else if (squarePath !== undefined && reason === 'not_standing') {
-        lines.push(participantsRecoveryCommand(squarePath));
+        lines.push(options.surface === 'tool' ? formatToolAction('status', { location: displayPath(squarePath) }) : `${commandPrefix(squarePath)} status`);
     }
     else if (squarePath !== undefined && reason === 'not_addressed' && facts?.activityId !== undefined) {
-        lines.push(facts.activityExists === true
+        lines.push(options.surface === 'tool' ? (facts.activityExists === true ? formatToolAction('history', { location: displayPath(squarePath), at: [facts.activityId], context: 2 }) : formatToolAction('history', { location: displayPath(squarePath), limit: 10 })) : facts.activityExists === true
             ? `${commandPrefix(squarePath)} history --at ${facts.activityId} -C 2`
             : `${commandPrefix(squarePath)} history --limit 10`);
     }
-    if (reason === 'invalid_done_body')
+    if (reason === 'invalid_done_body' && options.surface !== 'tool')
         lines.push('square done --help');
     return lines;
 }

package/dist/packages/agent-delivery/src/index.d.ts

@@ -1,6 +1,6 @@
 import { DeliveryError } from './errors.js';
-import type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions, CodexConnectOptions, CodexAppServerConnectOptions, CodexCliConnectOptions } from './types.js';
-export type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions, CodexConnectOptions, CodexAppServerConnectOptions, CodexCliConnectOptions } from './types.js';
+import type { OpenCodeConnectOptions, PiConnectOptions, PaseoConnectOptions, CodexConnectOptions, CodexAppServerConnectOptions, CodexCliConnectOptions } from './types.js';
+export type { OpenCodeConnectOptions, PiConnectOptions, PaseoConnectOptions, CodexConnectOptions, CodexAppServerConnectOptions, CodexCliConnectOptions } from './types.js';
 export interface SendOptions {
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
@@ -10,7 +10,7 @@ export interface KeyedSendOptions extends SendOptions {
 }
 export interface Receipt {
     readonly id: string;
-    readonly proof: 'written' | 'admitted' | 'observed';
+    readonly proof: 'admitted' | 'observed';
 }
 export interface Steerable<O = SendOptions> {
     steer(text: string, options?: O): Promise<Receipt>;
@@ -22,10 +22,6 @@ export type OpenCodeAgent = Steerable<KeyedSendOptions> & Queueable<KeyedSendOpt
     readonly harness: 'opencode';
     readonly sessionId: string;
 };
-export type ClaudeAgent = Steerable & {
-    readonly harness: 'claude';
-    readonly sessionId: string;
-};
 export type PiAgent = Steerable & Queueable & {
     readonly harness: 'pi';
     readonly sessionId: string;
@@ -47,9 +43,8 @@ export type CodexCliAgent = Queueable & {
     readonly sessionId: string;
 };
 export type CodexAgent = CodexAppServerAgent | CodexCliAgent;
-export type Agent = OpenCodeAgent | ClaudeAgent | PiAgent | PaseoAgent | CodexAgent;
+export type Agent = OpenCodeAgent | PiAgent | PaseoAgent | CodexAgent;
 export declare function connect(options: OpenCodeConnectOptions): Promise<OpenCodeAgent>;
-export declare function connect(options: ClaudeConnectOptions): Promise<ClaudeAgent>;
 export declare function connect(options: PiConnectOptions): Promise<PiAgent>;
 export declare function connect(options: PaseoConnectOptions): Promise<PaseoAgent>;
 export declare function connect(options: CodexCliConnectOptions): Promise<CodexCliAgent>;

package/dist/packages/agent-delivery/src/index.js

@@ -58,15 +58,6 @@ const harnesses = {
             return { coordinate: target.sessionId, send: (text, value) => sendText(target, text, value) };
         },
     },
-    claude: {
-        harness: 'claude', proof: 'written', accepted: 'written', coordinate: 'sessionId', keyed: false, queue: false,
-        id: (result) => result.messageId,
-        open: async (options) => {
-            const { connectExisting, sendText } = await import('./claude.js');
-            const target = await connectExisting(options);
-            return { coordinate: target.sessionId, send: (text, value) => sendText(target, text, value) };
-        },
-    },
     pi: {
         harness: 'pi', proof: 'observed', accepted: 'observed', coordinate: 'sessionId', keyed: false, queue: true,
         id: (result) => result.inputId,

package/dist/packages/agent-delivery/src/local-endpoint.d.ts

@@ -1,20 +1,12 @@
 import net from 'node:net';
 export interface LocalEndpoint {
-    readonly kind: 'unix' | 'pipe';
-    /** What the socket connects to. */
     readonly path: string;
-    /** What the native receiver fingerprints; also the auth key file digest input. */
-    readonly canonical: string;
 }
-/**
- * A local endpoint is either a Windows named pipe or an absolute Unix socket
- * path. There is no `stat().isSocket()` check: connecting is the existence check.
- */
+/** An absolute Unix socket path; connecting is the existence check. */
 export declare function parseLocalEndpoint(raw: unknown): LocalEndpoint;
 export declare class LocalEndpointError extends Error {
     readonly code: 'unavailable' | 'aborted' | 'timeout' | 'transport';
-    readonly maybeDelivered: boolean;
-    constructor(code: LocalEndpointError['code'], maybeDelivered?: boolean);
+    constructor(code: LocalEndpointError['code']);
 }
 export interface LocalConnectScope {
     readonly signal?: AbortSignal;
@@ -22,5 +14,3 @@ export interface LocalConnectScope {
 }
 /** Connect with bounded waiting. A connect failure is `unavailable`: nothing was written. */
 export declare function connectLocal(endpoint: LocalEndpoint, scope?: LocalConnectScope): Promise<net.Socket>;
-/** LF-delimited JSON frames. Any failure here is past the uncertainty boundary. */
-export declare function writeFrames(socket: net.Socket, frames: object[]): Promise<void>;