@astrosheep/square 0.4.6 → 0.4.8

package/dist/packages/agent-delivery/src/local-endpoint.js

@@ -1,35 +1,20 @@
 import net from 'node:net';
 import { resolve } from 'node:path';
-/** Claude's own pipe spelling: `\\.\pipe\<lowercased name>`. */
-const PIPE = /^[\\/]{2}[.?][\\/]pipe[\\/](?:(LOCAL)[\\/])?([^\\/]+)$/i;
-/**
- * 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 function parseLocalEndpoint(raw) {
-    if (typeof raw !== 'string' || raw.includes('\0'))
-        throw new Error('Invalid local endpoint.');
-    const pipe = PIPE.exec(raw);
-    if (pipe) {
-        const canonical = `\\\\.\\pipe\\${pipe[2].toLowerCase()}`;
-        return { kind: 'pipe', path: canonical, canonical };
-    }
-    if (!(process.platform === 'win32' ? /^[A-Za-z]:[\\/]/.test(raw) : raw.startsWith('/')))
+    if (typeof raw !== 'string' || raw.includes('\0') || !raw.startsWith('/'))
         throw new Error('Invalid local endpoint.');
     const limit = process.platform === 'darwin' ? 103 : process.platform === 'linux' ? 107 : undefined;
     if (limit !== undefined && Buffer.byteLength(raw) > limit)
         throw new Error('Invalid local endpoint.');
-    const canonical = resolve(raw);
-    return { kind: 'unix', path: canonical, canonical };
+    return { path: resolve(raw) };
 }
 export class LocalEndpointError extends Error {
     code;
-    maybeDelivered;
-    constructor(code, maybeDelivered = false) {
+    constructor(code) {
         super(code);
         this.name = 'LocalEndpointError';
         this.code = code;
-        this.maybeDelivered = maybeDelivered;
     }
 }
 function errnoCode(error) {
@@ -83,32 +68,3 @@ export function connectLocal(endpoint, scope = {}) {
         }
     });
 }
-/** LF-delimited JSON frames. Any failure here is past the uncertainty boundary. */
-export function writeFrames(socket, frames) {
-    const payload = frames.map((frame) => JSON.stringify(frame)).join('\n') + '\n';
-    return new Promise((resolveWrite, reject) => {
-        let settled = false;
-        // Error/close handlers stay attached past settling, so a later I/O failure is
-        // swallowed here instead of surfacing as an unhandled socket event.
-        const finish = (error) => {
-            if (settled)
-                return;
-            settled = true;
-            if (error) {
-                reject(error);
-                return;
-            }
-            resolveWrite();
-        };
-        const failed = (error) => finish(new LocalEndpointError(errnoCode(error), true));
-        socket.once('error', failed);
-        socket.once('close', () => finish(new LocalEndpointError('transport', true)));
-        socket.end(payload, 'utf8', (error) => {
-            if (error) {
-                failed(error);
-                return;
-            }
-            finish();
-        });
-    });
-}

package/dist/packages/agent-delivery/src/pi-client.js

@@ -55,8 +55,6 @@ export async function connectPi(options) {
     }
     if (process.platform !== 'darwin')
         throw new ConnectionError('unsupported_platform');
-    if (endpoint.kind !== 'unix')
-        throw new ConnectionError('invalid_arguments');
     const answer = await request(endpoint, { protocol: VERSION, harness: 'pi', op: 'hello', sessionId: options.sessionId }, options.timeoutMs, options.signal);
     if (answer.code !== undefined)
         throw new ConnectionError(answer.code === 'transport' ? 'service_unavailable' : answer.code);

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

@@ -5,11 +5,6 @@ export interface OpenCodeTarget {
     readonly sessionId: string;
     readonly [targetBrand]: true;
 }
-export interface ClaudeTarget {
-    readonly harness: 'claude';
-    readonly sessionId: string;
-    readonly [targetBrand]: true;
-}
 export interface PiTarget {
     readonly harness: 'pi';
     readonly sessionId: string;
@@ -25,7 +20,7 @@ export interface CodexTarget {
     readonly sessionId: string;
     readonly [targetBrand]: true;
 }
-export type Target = OpenCodeTarget | ClaudeTarget | PiTarget | PaseoTarget | CodexTarget;
+export type Target = OpenCodeTarget | PiTarget | PaseoTarget | CodexTarget;
 export type Delivery = 'steer' | 'queue';
 export interface OpenCodeSendTextOptions {
     readonly delivery?: Delivery;
@@ -33,12 +28,6 @@ export interface OpenCodeSendTextOptions {
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }
-export interface ClaudeSendTextOptions {
-    readonly delivery?: 'steer';
-    readonly inputId?: never;
-    readonly timeoutMs?: number;
-    readonly signal?: AbortSignal;
-}
 export interface PiSendTextOptions {
     readonly delivery?: Delivery;
     readonly inputId?: never;
@@ -58,7 +47,7 @@ export interface CodexSendTextOptions {
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }
-export type SendTextOptions = OpenCodeSendTextOptions | ClaudeSendTextOptions | PiSendTextOptions | PaseoSendTextOptions | CodexSendTextOptions;
+export type SendTextOptions = OpenCodeSendTextOptions | PiSendTextOptions | PaseoSendTextOptions | CodexSendTextOptions;
 export interface OpenCodeConnectOptions {
     readonly harness: 'opencode';
     readonly sessionId: string;
@@ -74,15 +63,6 @@ export interface OpenCodeConnectOptions {
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }
-export interface ClaudeConnectOptions {
-    readonly harness: 'claude';
-    readonly sessionId: string;
-    readonly endpoint: string;
-    readonly token?: string;
-    readonly claudeHome?: string;
-    readonly timeoutMs?: number;
-    readonly signal?: AbortSignal;
-}
 export interface PiConnectOptions {
     readonly harness: 'pi';
     readonly sessionId: string;
@@ -147,20 +127,6 @@ export type OpenCodeDeliveryResult = (OpenCodeAttempt & {
     readonly state: 'unavailable';
     readonly code: 'aborted' | 'timeout';
 });
-interface ClaudeAttempt {
-    readonly harness: 'claude';
-    readonly sessionId: string;
-}
-export type ClaudeDeliveryResult = (ClaudeAttempt & {
-    readonly state: 'written';
-    readonly messageId: string;
-}) | (ClaudeAttempt & {
-    readonly state: 'unknown';
-    readonly code: 'timeout' | 'aborted' | 'transport';
-}) | (ClaudeAttempt & {
-    readonly state: 'unavailable';
-    readonly code: 'aborted' | 'timeout' | 'endpoint_unavailable' | 'authentication_failed';
-});
 interface PiAttempt {
     readonly harness: 'pi';
     readonly sessionId: string;
@@ -214,5 +180,5 @@ export type CodexDeliveryResult = (CodexAttempt & {
     readonly state: 'rejected';
     readonly code: 'not_found' | 'refused' | 'unsupported_version';
 });
-export type DeliveryResult = OpenCodeDeliveryResult | ClaudeDeliveryResult | PiDeliveryResult | PaseoDeliveryResult | CodexDeliveryResult;
+export type DeliveryResult = OpenCodeDeliveryResult | PiDeliveryResult | PaseoDeliveryResult | CodexDeliveryResult;
 export {};

package/dist/participant-identity.d.ts

@@ -14,8 +14,6 @@ export interface HarnessSessionSource {
     readonly childVariable?: 'CLAUDE_CODE_CHILD_SESSION';
 }
 export declare const harnessSessionSources: readonly HarnessSessionSource[];
-/** Scope a native call without changing the harness-owned process environment. */
-export declare function operationEnv(provider: AutomaticProvider, sessionId: string, env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** Raw nonempty harness session ids in table order. Duplicates are preserved, never collapsed. */
 export declare function sessionIdsFromEnvironment(env?: NodeJS.ProcessEnv): readonly string[];
 /** The first nonempty harness coordinate in table order, or undefined when none is set. */

package/dist/participant-identity.js

@@ -8,19 +8,6 @@ export const harnessSessionSources = [
     { variable: 'PI_SESSION_ID', channel: 'pi', provider: 'pi' },
     { variable: 'PASEO_AGENT_ID', channel: 'paseo' },
 ];
-/** Scope a native call without changing the harness-owned process environment. */
-export function operationEnv(provider, sessionId, env) {
-    const scoped = { ...env };
-    // Clear other native coordinates (and the Claude child flag); PASEO_AGENT_ID stays as it is.
-    for (const source of harnessSessionSources) {
-        if (source.provider === undefined)
-            continue;
-        scoped[source.variable] = source.provider === provider ? sessionId : '';
-        if (source.childVariable !== undefined)
-            scoped[source.childVariable] = '';
-    }
-    return scoped;
-}
 /** Raw nonempty harness session ids in table order. Duplicates are preserved, never collapsed. */
 export function sessionIdsFromEnvironment(env = process.env) {
     return harnessSessionSources

package/dist/plugins/paseo/shared/card-format.d.ts

@@ -0,0 +1,6 @@
+import type { CardPresentation } from "./card-presentation.ts";
+export declare function reachLabel(reach?: CardPresentation["reach"]): string | undefined;
+/** Calendar days, rather than elapsed hours, keep yesterday correct across DST. */
+export declare function timeLabel(at: number, now?: number, compact?: boolean): string;
+/** Only adjacent references from the same origin can form a range. */
+export declare function cardReferences(items: readonly CardPresentation[], originLabel?: (origin: string) => string): string;

package/dist/plugins/paseo/shared/card-format.js

@@ -0,0 +1,38 @@
+export function reachLabel(reach) {
+    return reach === "mention" ? "@you" : reach === "attention" ? undefined : reach;
+}
+/** Calendar days, rather than elapsed hours, keep yesterday correct across DST. */
+export function timeLabel(at, now = Date.now(), compact = false) {
+    const date = new Date(at), today = new Date(now);
+    const day = (value) => `${value.getFullYear()}-${value.getMonth()}-${value.getDate()}`;
+    const clock = `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+    if (day(date) === day(today))
+        return clock;
+    const yesterday = new Date(today);
+    yesterday.setDate(today.getDate() - 1);
+    if (day(date) === day(yesterday))
+        return `${compact ? "yest" : "yesterday"} ${clock}`;
+    const shortDate = compact
+        ? `${String(date.getMonth() + 1).padStart(2, "0")}/${String(date.getDate()).padStart(2, "0")}`
+        : date.toLocaleDateString("en-US", { month: "short", day: "numeric" });
+    return `${shortDate} ${clock}`;
+}
+/** Only adjacent references from the same origin can form a range. */
+export function cardReferences(items, originLabel = origin => origin) {
+    const multipleOrigins = new Set(items.map(item => item.origin)).size > 1;
+    const runs = [];
+    for (const item of items) {
+        if (item.ref === undefined)
+            continue;
+        const match = /^act\/(\d+)$/.exec(item.ref);
+        const index = match ? Number(match[1]) : undefined;
+        const previous = runs.at(-1);
+        if (index !== undefined && previous?.origin === item.origin && previous.last !== undefined && previous.last + 1 === index) {
+            previous.last = index;
+        }
+        else
+            runs.push({ origin: item.origin, ref: item.ref, first: index, last: index });
+    }
+    return runs.map(run => `${multipleOrigins ? `${originLabel(run.origin)} ` : ""}${run.first !== run.last
+        ? `act/${run.first}–${run.last}` : run.ref}`).join(", ");
+}

package/dist/plugins/paseo/shared/card-presentation.d.ts

@@ -4,7 +4,9 @@ export type CardPresentation = {
     readonly origin: string;
     readonly author?: string;
     readonly ref?: string;
-    readonly badge?: string;
+    /** Absent on cards produced before landing time and reach were recorded. */
+    readonly at?: number;
+    readonly reach?: 'mention' | 'reply' | 'attention' | 'bell';
     readonly body: string;
 };
 export declare function isCardPresentation(value: unknown): value is CardPresentation;

package/dist/plugins/paseo/shared/card-presentation.js

@@ -3,5 +3,7 @@ export function isCardPresentation(value) {
         return false;
     const item = value;
     return item.kind === 'presentation' && typeof item.origin === 'string' && typeof item.body === 'string'
-        && ['author', 'ref', 'badge'].every(key => item[key] === undefined || typeof item[key] === 'string');
+        && (item.at === undefined || (typeof item.at === 'number' && Number.isFinite(item.at)))
+        && (item.reach === undefined || ['mention', 'reply', 'attention', 'bell'].includes(item.reach))
+        && ['author', 'ref'].every(key => item[key] === undefined || typeof item[key] === 'string');
 }

package/dist/presentation.d.ts

@@ -2,6 +2,8 @@ import { type HydratedAct, 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 PresentationSurface = 'cli' | 'tool';
+export declare function formatToolAction(tool: string, args?: Readonly<Record<string, unknown>>): string;
 export type WatchStatus = 'idle' | 'drained' | 'quorum' | 'capped';
 interface HeaderOptions {
     participantCount?: number;
@@ -9,31 +11,16 @@ interface HeaderOptions {
     plain?: boolean;
 }
 interface ParticipantOutputOptions {
+    surface?: PresentationSurface;
     owner?: string;
     squarePath: string;
     name: string;
     participantCount?: number;
 }
-interface ActivityLimitOptions extends ParticipantOutputOptions {
-    count?: number;
-    hardCap?: number;
-    draftPath?: string;
-}
-interface ActivityBlockedOptions extends ParticipantOutputOptions {
-    retryCommand: string;
-    activitySummaries: readonly UnreadActivitySummary[];
-    draftPath?: string;
-}
 interface ExpressWaitingOptions {
     reason: 'throttled';
     delayMs?: number;
 }
-interface ExpressNoWaitOptions extends ParticipantOutputOptions {
-    reason: 'throttled';
-    retryCommand: string;
-    delayMs?: number;
-    draftPath?: string;
-}
 interface WatchStatusOptions extends ParticipantOutputOptions {
     status: WatchStatus;
     idleMs?: number;
@@ -51,7 +38,6 @@ export declare function withPathOutput(squarePath: string, body?: string, opts?:
 export declare function formatRefusal(squarePath: string, bodyLines: string[], opts?: {
     participantCount?: number;
 }): 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, owner?: string): string;
@@ -59,7 +45,6 @@ export declare function participantCommandPrefix(squarePath: string, name: strin
 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, 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): {
     text: string;
@@ -91,7 +76,7 @@ export declare function renderAmbientEvent(event: HydratedAct | Activity, viewer
     mention?: string;
     perception?: Perception;
 }): string;
-export declare function renderActivityBlocked(opts: ActivityBlockedOptions): string;
+export declare function renderUnreadSummary(activitySummaries: readonly UnreadActivitySummary[]): string[];
 /** An indeterminate or already-committed send only points to inspection, never resend. */
 export declare function renderActivityUncertain(opts: ParticipantOutputOptions & {
     draftPath: string;
@@ -99,10 +84,8 @@ export declare function renderActivityUncertain(opts: ParticipantOutputOptions &
     detail?: string;
 }): string;
 export declare function renderExpressWaiting(opts: ExpressWaitingOptions): string;
-export declare function renderExpressNoWait(opts: ExpressNoWaitOptions): string;
 export declare function renderPresenceAnchor(names: readonly string[]): string;
-export declare function renderGrepActivitiesView(visible: readonly HydratedAct[], totalMatches: number, noTruncate: boolean | undefined, squarePath: string, pattern: string, fixed?: boolean, perception?: (act: HydratedAct) => Perception): string;
-export declare function renderActivityLimit(opts: ActivityLimitOptions): string;
+export declare function renderGrepActivitiesView(visible: readonly HydratedAct[], totalMatches: number, full: boolean | undefined, squarePath: string, pattern: string, fixed?: boolean, perception?: (act: HydratedAct) => Perception, surface?: PresentationSurface): string;
 export declare function renderWatchAlreadyActive(opts: ParticipantOutputOptions): string;
 export declare function renderWatchForceTakeover(_opts: ParticipantOutputOptions): string;
 export declare function renderWatchReplaceMissing(_opts: ParticipantOutputOptions): string;

package/dist/presentation.js

@@ -1,4 +1,4 @@
-import { sameName, isSquareError } from './model.js';
+import { sameName } from './model.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import { participantIdentity } from './participant-identity.js';
@@ -7,6 +7,10 @@ import { formatActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
 import { formatDuration, formatRelativeTime, formatTimestamp } from './time.js';
 import { grepSnippet } from './search.js';
 import { style } from './tty-style.js';
+export function formatToolAction(tool, args = {}) {
+    const clean = Object.fromEntries(Object.entries(args).filter(([, value]) => value !== undefined));
+    return Object.keys(clean).length === 0 ? tool : `${tool} ${JSON.stringify(clean)}`;
+}
 export function displayPath(squarePath, cwd = process.cwd()) {
     if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(squarePath))
         return squarePath;
@@ -37,11 +41,6 @@ export function formatRefusal(squarePath, bodyLines, opts = {}) {
         return body === '' ? '' : `${body}\n`;
     return withPathOutput(squarePath, body, { ...opts, plain: true });
 }
-export function refusalText(error) {
-    const text = error instanceof Error ? error.message : String(error);
-    const marked = isSquareError(error) && ['never_joined', 'not_standing'].includes(error.facts?.reason ?? '');
-    return marked ? text.split('\n').map((line) => `✕ ${line}`).join('\n') : text;
-}
 export function quoteShell(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -58,13 +57,10 @@ export function joinRecoveryCommand(squarePath, name, owner) {
 /** Taking a name is an explicit recovery choice, never an automatic retry. */
 export function takeoverRecoveryLines(squarePath, name, owner) {
     return [
-        'If this is your name to reclaim, --kick banishes the one standing here so you can step in:',
-        `${participantCommandPrefix(squarePath, name, owner)} join --kick`,
+        'If this is your name to reclaim, --takeover banishes the one standing here so you can step in:',
+        `${participantCommandPrefix(squarePath, name, owner)} join --takeover`,
     ];
 }
-export function participantsRecoveryCommand(squarePath) {
-    return `${commandPrefix(squarePath)} participants`;
-}
 function formatAge(ms) {
     if (ms === undefined)
         return '(none)';
@@ -218,17 +214,14 @@ export function renderAmbientEvent(event, viewer, opts = {}) {
 function draftSavedLines(draftPath) {
     return draftPath === undefined ? [] : [style('dim', `· draft kept: ${draftPath}`)];
 }
-function withDraftInput(command, draftPath) {
-    return draftPath === undefined ? command : `${command} < ${quoteShell(draftPath)}`;
-}
-function renderUnreadSummary(activitySummaries) {
+export function renderUnreadSummary(activitySummaries) {
     const visibleSummaries = activitySummaries.slice(0, MAX_IDENTITY_SET_SIZE);
     const remainingSummaries = activitySummaries.length - visibleSummaries.length;
     return [
         ...visibleSummaries.map((item) => {
             const compact = (item.preview.body ?? '').replace(/\s+/g, ' ').trim();
             const bodyPreview = compact === ''
-                ? { text: item.preview.metadata === undefined ? '(empty)' : '(structured activity)', remaining: 0 }
+                ? { text: item.preview.structured ? '(structured activity)' : '(empty)', remaining: 0 }
                 : truncateChars(compact, UNREAD_PREVIEW_CHARS);
             const bodyText = bodyPreview.remaining === 0 ? bodyPreview.text : `${bodyPreview.text}${style('dim', `… (+${bodyPreview.remaining} chars)`)}`;
             return style('dim', `  · ${participantIdentity(item.name)} spoke — ${formatAge(item.latestActivityAgeMs)} ago · "${bodyText}"`);
@@ -236,17 +229,6 @@ function renderUnreadSummary(activitySummaries) {
         ...(remainingSummaries === 0 ? [] : [style('dim', `  · ${remainingSummaries} more participants have unread activity`)]),
     ];
 }
-export function renderActivityBlocked(opts) {
-    const readNowCommand = `${participantCommandPrefix(opts.squarePath, opts.name, opts.owner)} perceive`;
-    return withPathOutput(opts.squarePath, [
-        `${style('blocked', '✕')} your activity hasn't landed — someone spoke while you were away`,
-        ...renderUnreadSummary(opts.activitySummaries),
-        ...draftSavedLines(opts.draftPath),
-        `${readNowCommand}`,
-        '  · take it in, then retry:',
-        withDraftInput(opts.retryCommand, opts.draftPath),
-    ].join('\n'), { participantCount: opts.participantCount });
-}
 /** An indeterminate or already-committed send only points to inspection, never resend. */
 export function renderActivityUncertain(opts) {
     return formatRefusal(opts.squarePath, [
@@ -256,7 +238,7 @@ export function renderActivityUncertain(opts) {
         ...(opts.detail === undefined ? [] : [`  · ${truncateExternalDiagnostic(opts.detail)}`]),
         ...draftSavedLines(opts.draftPath),
         '  · the draft is a saved copy; sending it again could repeat your activity',
-        `${commandPrefix(opts.squarePath)} history${opts.landedId === undefined ? ' --limit 10' : ` --at ${opts.landedId}`} --no-truncate`,
+        `${commandPrefix(opts.squarePath)} history${opts.landedId === undefined ? ' --limit 10' : ` --at ${opts.landedId}`} --full`,
     ], opts);
 }
 export function renderExpressWaiting(opts) {
@@ -266,16 +248,6 @@ export function renderExpressWaiting(opts) {
         '  · --no-wait saves a draft and returns now',
     ].join('\n');
 }
-export function renderExpressNoWait(opts) {
-    const retryCommand = opts.retryCommand;
-    const lines = [
-        `${style('blocked', '✕')} the square is packed — shoulder to shoulder`,
-        `  · a lull opens in ${formatDuration(opts.delayMs)}`,
-        ...draftSavedLines(opts.draftPath),
-        `${withDraftInput(retryCommand, opts.draftPath)}`,
-    ];
-    return withPathOutput(opts.squarePath, lines.join('\n'), { participantCount: opts.participantCount });
-}
 export function renderPresenceAnchor(names) {
     const visibleNames = names.slice(0, MAX_IDENTITY_SET_SIZE);
     const participants = visibleNames.map((name) => participantIdentity(name)).join(', ');
@@ -284,7 +256,7 @@ export function renderPresenceAnchor(names) {
     return style('dim', names.length === 1 ? `→ ${participants} was here` : `→ ${participants}${suffix} were here`);
 }
 const GREP_PREVIEW_CHARS = 160;
-export function renderGrepActivitiesView(visible, totalMatches, noTruncate, squarePath, pattern, fixed = false, perception) {
+export function renderGrepActivitiesView(visible, totalMatches, full, squarePath, pattern, fixed = false, perception, surface = 'cli') {
     const publicVisible = visible.filter((act) => act.kind === 'say' || act.kind === 'done');
     if (totalMatches === 0)
         return `○ no activity matched ${quoteShell(pattern)}`;
@@ -298,7 +270,7 @@ export function renderGrepActivitiesView(visible, totalMatches, noTruncate, squa
             chunks.push(header);
             continue;
         }
-        if (noTruncate === true) {
+        if (full === true) {
             const body = rawBody.split('\n').map((line) => `  ${line}`).join('\n');
             chunks.push(`${header}\n${body}`);
             continue;
@@ -319,30 +291,25 @@ export function renderGrepActivitiesView(visible, totalMatches, noTruncate, squa
         chunks.push(`${header}\n  ${text.trim()}${omitted}`);
     }
     if (publicVisible.length === 1) {
-        chunks.push(`${commandPrefix(squarePath)} history --at ${formatActivityId(publicVisible[0].index)} -C 2${truncated ? ' --no-truncate' : ''}`);
+        chunks.push(surface === 'tool'
+            ? formatToolAction('history', { location: displayPath(squarePath), at: [formatActivityId(publicVisible[0].index)], context: 2, ...(truncated ? { full: true } : {}) })
+            : `${commandPrefix(squarePath)} history --at ${formatActivityId(publicVisible[0].index)} -C 2${truncated ? ' --full' : ''}`);
     }
     else if (truncated && publicVisible.length > 1) {
-        chunks.push(`${commandPrefix(squarePath)} history --at ${formatActivityId(publicVisible[0].index)} -C 2 --no-truncate`);
+        chunks.push(surface === 'tool'
+            ? formatToolAction('history', { location: displayPath(squarePath), at: [formatActivityId(publicVisible[0].index)], context: 2, full: true })
+            : `${commandPrefix(squarePath)} history --at ${formatActivityId(publicVisible[0].index)} -C 2 --full`);
     }
     return chunks.join('\n\n');
 }
-export function renderActivityLimit(opts) {
-    // The cap wording lives inside the count: the speaker is simply spent.
-    const spoken = opts.count !== undefined && opts.hardCap !== undefined ? ` — ${opts.count}/${opts.hardCap} spoken` : '';
-    const doneCommand = `${participantCommandPrefix(opts.squarePath, opts.name, opts.owner)} done`;
-    return withPathOutput(opts.squarePath, [
-        `${style('blocked', '✕')} you’ve reached your speaking cap${spoken}`,
-        ...draftSavedLines(opts.draftPath),
-        '  · your draft stays unsent; done only steps out',
-        doneCommand,
-    ].join('\n'), { participantCount: opts.participantCount });
-}
 export function renderWatchAlreadyActive(opts) {
     return [
         `${style('blocked', '✕')} you are already perceiving`,
         `  · an active perceive is already running for ${participantIdentity(opts.name)}`,
-        '  · --replace lets a new perceive take over',
-        `${participantCommandPrefix(opts.squarePath, opts.name, opts.owner)} perceive --idle 30m --replace`,
+        `  · ${opts.surface === 'tool' ? 'takeover' : '--takeover'} lets a new perceive take over`,
+        opts.surface === 'tool'
+            ? formatToolAction('perceive', { location: displayPath(opts.squarePath), as: opts.name, idle: '30m', takeover: true })
+            : `${participantCommandPrefix(opts.squarePath, opts.name, opts.owner)} perceive --idle 30m --takeover`,
     ].join('\n');
 }
 export function renderWatchForceTakeover(_opts) {
@@ -373,7 +340,7 @@ export function renderWatchStatus(opts) {
                     ? style('dim', `○ dust settles on the flagstones — ${formatDuration(idleMs)} of quiet`)
                     : style('dim', '○ only footsteps in the square — nothing new for you');
             // The quiet report never repeats the perceive just run.
-            const hints = [`${prefix} perceive --idle 30m`];
+            const hints = [opts.surface === 'tool' ? formatToolAction('perceive', { location: displayPath(opts.squarePath), as: opts.name, idle: '30m' }) : `${prefix} perceive --idle 30m`];
             return [
                 quiet,
                 ...(opts.showPerceiveHint === false ? [] : hints),
@@ -381,12 +348,12 @@ export function renderWatchStatus(opts) {
             ].join('\n');
         }
         case 'quorum':
-            return [`${style('release', '✓')} everyone else has left — the square is yours alone`, `${participantCommandPrefix(opts.squarePath, opts.name, opts.owner)} done`].join('\n');
+            return [`${style('release', '✓')} everyone else has left — the square is yours alone`, opts.surface === 'tool' ? formatToolAction('done', { location: displayPath(opts.squarePath), as: opts.name }) : `${participantCommandPrefix(opts.squarePath, opts.name, opts.owner)} done`].join('\n');
         case 'capped': {
             const spoken = opts.hardCap === undefined || opts.hardCap === null
                 ? ''
                 : ` — ${opts.ownActivityCount ?? 0}/${opts.hardCap} spoken`;
-            return [`${style('blocked', '✕')} you’ve reached your speaking cap${spoken}`, `${participantCommandPrefix(opts.squarePath, opts.name, opts.owner)} done`].join('\n');
+            return [`${style('blocked', '✕')} you’ve reached your speaking cap${spoken}`, opts.surface === 'tool' ? formatToolAction('done', { location: displayPath(opts.squarePath), as: opts.name }) : `${participantCommandPrefix(opts.squarePath, opts.name, opts.owner)} done`].join('\n');
         }
     }
 }

package/dist/runtime.d.ts

@@ -1,9 +1,9 @@
-import { type WatchLease } from './model.js';
+import type { WatchLease } from './model.js';
 import type { ParticipantCounts, ParticipantFact, SquareRead } from './ports.js';
-export declare const WATCH_HEARTBEAT_MS: number;
-export declare const WATCH_STALE_MS: number;
-export declare const THROTTLE_WINDOW_MS: number;
-export declare const UNREAD_BLOCK_GRACE_MS: number;
+export declare const WATCH_HEARTBEAT_MS = 60000;
+export declare const WATCH_STALE_MS = 180000;
+export declare const THROTTLE_WINDOW_MS = 60000;
+export declare const UNREAD_BLOCK_GRACE_MS = 90000;
 export declare const FACT_PAGE_SIZE = 100;
 export declare function inSquareCount(facts: SquareRead): number;
 export declare function terminalStatusFor(current: ParticipantFact | undefined, hardCap: number | null, counts: ParticipantCounts): 'capped' | 'quorum' | undefined;
@@ -12,4 +12,4 @@ export declare function watchTerminalStatus(facts: SquareRead, name: string): 'c
 export declare function readCursor(facts: SquareRead, name: string): number;
 /** Presence rides on own activity or exact receipts, not nonaddressed cursor progress. */
 export declare function presenceAnchor(facts: SquareRead, name: string): number;
-export declare function freshWatchLease(facts: SquareRead, name: string, at?: number): WatchLease | undefined;
+export declare function freshWatchLease(facts: SquareRead, name: string, at: number): WatchLease | undefined;

package/dist/runtime.js

@@ -1,17 +1,7 @@
-import { SquareError } from './model.js';
-function parseIntegerEnv(name, fallback) {
-    const raw = process.env[name];
-    if (raw === undefined)
-        return fallback;
-    const value = parseInt(raw, 10);
-    if (!Number.isFinite(value) || value <= 0)
-        throw new SquareError('invalid_args', `Invalid ${name}: expected a positive integer.`);
-    return value;
-}
-export const WATCH_HEARTBEAT_MS = parseIntegerEnv('SQUARE_WATCH_HEARTBEAT_MS', 60000);
-export const WATCH_STALE_MS = parseIntegerEnv('SQUARE_WATCH_STALE_MS', 180000);
-export const THROTTLE_WINDOW_MS = parseIntegerEnv('SQUARE_THROTTLE_WINDOW_MS', 60000);
-export const UNREAD_BLOCK_GRACE_MS = parseIntegerEnv('SQUARE_UNREAD_BLOCK_GRACE_MS', 90000);
+export const WATCH_HEARTBEAT_MS = 60000;
+export const WATCH_STALE_MS = 180000;
+export const THROTTLE_WINDOW_MS = 60000;
+export const UNREAD_BLOCK_GRACE_MS = 90000;
 export const FACT_PAGE_SIZE = 100;
 export function inSquareCount(facts) { return facts.participantCounts().joined; }
 export function terminalStatusFor(current, hardCap, counts) {
@@ -46,7 +36,7 @@ export function presenceAnchor(facts, name) {
     const evidence = Math.max(boundary, own ?? boundary, facts.receiptFacts(name, boundary).latestActorActivityIndex ?? boundary);
     return facts.activityHeads({ afterIndex: boundary, throughIndex: evidence, kinds: ['say', 'done'] }, { edge: 'newest', limit: 1 }).items[0]?.index ?? -1;
 }
-export function freshWatchLease(facts, name, at = Date.now()) {
+export function freshWatchLease(facts, name, at) {
     const lease = facts.lease(name);
     return lease === undefined || lease.expiresAt <= at || at - lease.heartbeatAt > WATCH_STALE_MS ? undefined : lease;
 }

package/dist/sqlite-square.d.ts

@@ -1,7 +1,6 @@
 import { type Owner } from './model.js';
 import type { HistoryQuery, HistoryResult, JoinOptions, JoinResult, ObservationOptions, OperationControl, Participant, SquareAtInput, SquareBuildInput, SquareLocation, StatusOptions, StatusResult, ParticipantsResult, RecoveryResult, DiscoveryOptions, InboxOptions, InboxResult, StreamOptions, StreamRecord, Activity, PerceivedActivity, SendInput, SendResult } from './square-facade.js';
 export type * from './square-facade.js';
-export { squareClock } from './operation-control.js';
 export { formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
 export { PERCEIVE_DEFAULT_LIMIT, PERCEIVE_MAX_LIMIT } from './perceive-decisions.js';
 export { HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
@@ -11,8 +10,8 @@ export declare class SqliteSquare {
     readonly location: string;
     private readonly artifact;
     private readonly clock;
-    private readonly env;
-    private readonly deliveryLocation;
+    private readonly canonicalLocation;
+    private readonly ledgerLocation?;
     private constructor();
     private reconcile;
     private flush;
@@ -51,5 +50,5 @@ export declare class SqliteSquare {
     close(): Promise<void>;
 }
 export declare function diagnoseSquare(input: SquareLocation, control?: OperationControl): Promise<import("./artifact.js").DiagnoseResult>;
-export declare function discover(input: SquareAtInput, options?: DiscoveryOptions, control?: OperationControl): Promise<import("./square-facade.js").DiscoveryResult>;
-export declare function inbox(input: SquareAtInput, owner: Owner, options?: InboxOptions, control?: OperationControl): Promise<InboxResult>;
+export declare function discover(input: SquareLocation, options?: DiscoveryOptions, control?: OperationControl): Promise<import("./square-facade.js").DiscoveryResult>;
+export declare function inbox(input: SquareLocation, owner: Owner, options?: InboxOptions, control?: OperationControl): Promise<InboxResult>;