@astrosheep/square 0.3.34 → 0.3.36

package/dist/decisions.js

@@ -1,16 +1,15 @@
 import { SquareError, sameName, validateName, } from './model.js';
 import { participantIdentity } from './participant-identity.js';
-import { UNREAD_BLOCK_GRACE_MS, actId, actStableIndex, foldedState, freshWatchLease, publicActs, resolveRosterName, rosterNames, THROTTLE_WINDOW_MS, } from './runtime.js';
+import { UNREAD_BLOCK_GRACE_MS, actId, actStableIndex, foldedState, freshWatchLease, publicActs, resolveRosterName, THROTTLE_WINDOW_MS, } from './runtime.js';
 import { actDelta, directedPeerSays } from './activity-feed.js';
-import { formatActivityId, isIgnored, isListening, listeningTo, validate } from './square-core.js';
+import { formatActivityId, isIgnored, isListening, listeningTo, MAX_IDENTITY_SET_SIZE, validate } from './square-core.js';
 import { deriveDeliveryModel } from './delivery.js';
 import { compileSearchPattern } from './search.js';
 export function resolveKnownName(squareState, name) {
     validateName(name);
     const known = resolveRosterName(squareState, name);
     if (known === undefined) {
-        const roster = rosterNames(squareState);
-        throw new SquareError('invalid_args', `Unknown participant "${participantIdentity(name)}". Expected one of: ${roster.map(participantIdentity).join(', ')}.`);
+        throw new SquareError('invalid_args', `Unknown participant "${participantIdentity(name)}".`);
     }
     return known;
 }
@@ -62,6 +61,8 @@ function requireStanding(squareState, act) {
         throw new SquareError('already_done', `${act.actor === undefined ? 'participant' : participantIdentity(act.actor)} is already done`);
     if (result.reason === 'not_joined')
         throw new SquareError('not_joined', `${act.actor === undefined ? 'participant' : participantIdentity(act.actor)} has not joined this square`);
+    if (result.reason === 'listening_limit')
+        throw new SquareError('invalid_args', `A participant can listen to at most ${result.limit} others`);
     throw new Error(`Unexpected standing validation result: ${result.reason}`);
 }
 const UNREAD_PREVIEW_LIMIT = 3;
@@ -72,6 +73,26 @@ export function decideAct(squareState, input) {
     if (body.trim() === '')
         throw new SquareError('invalid_args', 'express body cannot be empty');
     const reach = input.reach;
+    const state = foldedState(squareState);
+    const requestedMentions = input.mentions ?? [];
+    const mentionNames = [];
+    const joinedNames = state.participants.filter((participant) => participant.joined).map((participant) => participant.name);
+    for (const requested of requestedMentions) {
+        validateName(requested);
+        const resolved = joinedNames.find((candidate) => sameName(candidate, requested));
+        if (resolved === undefined) {
+            throw new SquareError('invalid_args', `Unknown mention target ${participantIdentity(requested)}.`);
+        }
+        if (!mentionNames.some((existing) => sameName(existing, resolved))) {
+            if (mentionNames.length >= MAX_IDENTITY_SET_SIZE) {
+                throw new SquareError('invalid_args', `An activity can mention at most ${MAX_IDENTITY_SET_SIZE} participants`);
+            }
+            mentionNames.push(resolved);
+        }
+    }
+    if (reach === 'bell' && mentionNames.length > 0) {
+        throw new SquareError('invalid_args', 'A bell cannot be combined with --mention.');
+    }
     const reply = input.reply;
     if (reply !== undefined) {
         if (!Number.isSafeInteger(reply) || reply < 0 || reply >= squareState.runtime.nextActIndex) {
@@ -79,16 +100,17 @@ export function decideAct(squareState, input) {
             throw new SquareError('invalid_args', `Unknown reply activity: ${label}`);
         }
     }
-    const state = foldedState(squareState);
     const current = participantState(state, name);
     const result = validate(state, {
-        kind: 'say', actor: name, at: now, body,
+        kind: 'say', actor: name, at: now, body, mentions: mentionNames,
         ...(reach !== undefined ? { reach } : {}),
         ...(reply !== undefined ? { reply } : {}),
     }, { hardCap: squareState.hardCap, throttlePerMinute: squareState.throttlePerMinute, throttleWindowMs: THROTTLE_WINDOW_MS });
     if (!result.ok) {
         if (result.reason === 'done')
             throw new SquareError('already_done', `${name} is already done`);
+        if (result.reason === 'mention_limit')
+            throw new SquareError('invalid_args', `An activity can mention at most ${result.limit} participants`);
         if (result.reason === 'held')
             return { type: 'held', reason: result.hold.reason };
         if (result.reason === 'hard_cap')
@@ -142,7 +164,7 @@ export function decideAct(squareState, input) {
     return {
         type: 'sent',
         act: {
-            kind: 'say', actor: name, at: now, body,
+            kind: 'say', actor: name, at: now, body, mentions: mentionNames,
             ...(reach !== undefined ? { reach } : {}),
             ...(reply !== undefined ? { reply } : {}),
         },
@@ -254,7 +276,6 @@ export function coreParticipants(squareState, now, delivery) {
 export function coreActivities(squareState, opts, suppliedDelivery) {
     const participants = opts.participants ?? [];
     const canonicalParticipants = participants.map((participant) => resolveKnownName(squareState, participant));
-    const viewer = opts.viewer !== undefined ? resolveKnownName(squareState, opts.viewer) : undefined;
     let acts = [...squareState.acts];
     let delivery = suppliedDelivery;
     const projected = () => delivery ??= deriveDeliveryModel(squareState);
@@ -285,12 +306,6 @@ export function coreActivities(squareState, opts, suppliedDelivery) {
         const mention = resolveKnownName(squareState, opts.mention);
         acts = acts.filter((act) => act.kind === 'say' && projected().plan(act).some((item) => sameName(item.recipient, mention)));
     }
-    if (opts.pending) {
-        if (viewer === undefined)
-            return [];
-        const pendingIndexes = new Set(projected().pendingFor(viewer).map((notification) => notification.item.index));
-        acts = acts.filter((act) => pendingIndexes.has(act.index));
-    }
     const search = opts.grep !== undefined ? { pattern: opts.grep, fixed: false } : opts.fixed !== undefined ? { pattern: opts.fixed, fixed: true } : undefined;
     if (search !== undefined && search.pattern !== '') {
         // Search only the public activity model rendered by history, but include all

package/dist/delivery-health.d.ts

@@ -18,4 +18,5 @@ export declare function classifyDeliveryHealth(squarePath: string, opts: {
     now?: number;
     env?: NodeJS.ProcessEnv;
 }): Promise<DeliveryHealthItem[]>;
+export declare function renderDeliveryHealth(items: readonly DeliveryHealthItem[]): string[];
 export declare function doctorDeliveryHealth(squarePath: string, graceMs: number, now?: number, env?: NodeJS.ProcessEnv): Promise<string[]>;

package/dist/delivery-health.js

@@ -1,5 +1,5 @@
 import { formatActivityId } from './square-core.js';
-import { participantIdentity } from './presentation.js';
+import { participantIdentity, truncateChars } from './presentation.js';
 import { formatDuration } from './time.js';
 import { wakeEvidence } from './wake-evidence.js';
 import { openSquare } from './square-file-adapter.js';
@@ -13,6 +13,8 @@ const DISPLAY_ORDER = [
     'unreachable',
 ];
 const ACTIONABLE = new Set(['wake-unknown', 'unreachable']);
+const DETAIL_LIMIT = 20;
+const DISPLAY_FIELD_LIMIT = 160;
 /** Purely classify current pending attention from the artifact and durable ledgers. */
 export async function classifyDeliveryHealth(squarePath, opts) {
     const now = opts.now ?? Date.now();
@@ -49,21 +51,32 @@ export async function classifyDeliveryHealth(squarePath, opts) {
     }
     return items;
 }
+function displayField(value) {
+    const truncated = truncateChars(value, DISPLAY_FIELD_LIMIT - 1);
+    return truncated.remaining === 0 ? truncated.text : `${truncated.text}…`;
+}
 function formatItem(item) {
-    const evidence = item.attempt?.signature === undefined ? '' : ` · ${item.attempt.signature}`;
-    return `  · ${formatActivityId(item.actIndex)} → ${participantIdentity(item.recipient)} from ${participantIdentity(item.actor)} · ${formatDuration(item.ageMs)}${evidence}`;
+    const evidence = item.attempt?.signature === undefined ? '' : ` · ${displayField(item.attempt.signature)}`;
+    return `  · ${formatActivityId(item.actIndex)} → ${displayField(participantIdentity(item.recipient))} from ${displayField(participantIdentity(item.actor))} · ${formatDuration(item.ageMs)}${evidence}`;
 }
-export async function doctorDeliveryHealth(squarePath, graceMs, now = Date.now(), env = process.env) {
-    const items = await classifyDeliveryHealth(squarePath, { graceMs, now, env });
+export function renderDeliveryHealth(items) {
     if (items.length === 0)
         return ['✓ no pending delivery attention'];
     const out = [`· delivery attention · ${items.length} pending`];
+    let displayed = 0;
     for (const kind of DISPLAY_ORDER) {
         const group = items.filter((item) => item.kind === kind);
         if (group.length === 0)
             continue;
         out.push(`${ACTIONABLE.has(kind) ? '✕' : '○'} ${kind}: ${group.length}`);
-        out.push(...group.map(formatItem));
+        const details = group.slice(0, DETAIL_LIMIT - displayed);
+        out.push(...details.map(formatItem));
+        displayed += details.length;
     }
+    if (items.length > DETAIL_LIMIT)
+        out.push(`${DETAIL_LIMIT} of ${items.length} pending details shown`);
     return out;
 }
+export async function doctorDeliveryHealth(squarePath, graceMs, now = Date.now(), env = process.env) {
+    return renderDeliveryHealth(await classifyDeliveryHealth(squarePath, { graceMs, now, env }));
+}

package/dist/delivery.d.ts

@@ -46,12 +46,14 @@ export interface WakeAdapter {
 export interface RoutedNotification {
     actor: string;
     body: string;
+    mentions?: readonly string[];
     route: DirectedNotificationRoute;
     recipient?: string;
 }
 export interface CatchFilterShape {
     actor: string;
     body: string;
+    mentions?: readonly string[];
     reach?: Reach;
     recipients?: readonly string[];
 }

package/dist/delivery.js

@@ -125,6 +125,7 @@ export function leaseOwnsNotification(lease, notification) {
     return matchesCatchFilter({
         actor: notification.actor,
         body: notification.body,
+        ...(notification.mentions === undefined ? {} : { mentions: notification.mentions }),
         ...(notification.recipient === undefined ? {} : { recipients: [notification.recipient] }),
         ...(notification.route === 'bell' ? { reach: 'bell' } : {}),
     }, lease.filter ?? {});

package/dist/harness-links.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import crossSpawn from 'cross-spawn';
 import { SQUARE_IDENTITY } from './identity.js';
+import { truncateExternalDiagnostic } from './presentation.js';
 function packageRoot() {
     // Emitted modules live in dist; package assets are one level above them.
     return fileURLToPath(new URL('../', import.meta.url));
@@ -75,7 +76,16 @@ export function doctorHarnessLinks(links) {
         : `○ Square ${link.kind ?? 'link'} missing ${link.target}`);
 }
 function runOpenCode(homeDir, args) {
-    const result = crossSpawn.sync(process.env.SQUARE_OPENCODE_BIN || 'opencode', args, {
+    const prefix = (() => {
+        try {
+            const parsed = JSON.parse(process.env.SQUARE_OPENCODE_BIN_ARGS ?? '[]');
+            return Array.isArray(parsed) && parsed.every((item) => typeof item === 'string') ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    })();
+    const result = crossSpawn.sync(process.env.SQUARE_OPENCODE_BIN || 'opencode', [...prefix, ...args], {
         encoding: 'utf8',
         env: { ...process.env, HOME: homeDir, XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME ?? path.join(homeDir, '.config') },
         timeout: 30_000,
@@ -125,7 +135,8 @@ export function verifyOpenCodeRuntime(homeDir, run = runOpenCode) {
     try {
         const result = run(homeDir, ['debug', 'config']);
         if (result.status !== 0) {
-            return `✕ OpenCode debug config failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`}`;
+            const diagnostic = result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`;
+            return `✕ OpenCode debug config failed: ${truncateExternalDiagnostic(diagnostic)}`;
         }
         let config;
         try {
@@ -141,7 +152,8 @@ export function verifyOpenCodeRuntime(homeDir, run = runOpenCode) {
         return `○ OpenCode npm plugin not loaded: ${expected}`;
     }
     catch (error) {
-        return `○ OpenCode runtime unavailable (${error instanceof Error ? error.message : String(error)})`;
+        const diagnostic = error instanceof Error ? error.message : String(error);
+        return `○ OpenCode runtime unavailable (${truncateExternalDiagnostic(diagnostic)})`;
     }
 }
 export function skillLinks(homeDir = os.homedir(), parents = ['.claude', '.agents']) {

package/dist/harness.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { doctorDeliveryHealth } from './delivery-health.js';
 import { wakeGraceMs } from './notifications.js';
+import { truncateExternalDiagnostic } from './presentation.js';
 import { doctorClaudePlugin, installClaudePlugin, uninstallClaudePlugin, } from './harness-claude.js';
 import { doctorCodexPlugin, installCodexPlugin, uninstallCodexPlugin, } from './harness-codex.js';
 import { doctorPiPackage, installPiPackage, uninstallPiPackage, } from './harness-pi.js';
@@ -13,7 +14,8 @@ async function doctorHost(label, inspect) {
         return result(await inspect());
     }
     catch (error) {
-        return result([`○ ${label} doctor unavailable (${error instanceof Error ? error.message : String(error)})`]);
+        const diagnostic = error instanceof Error ? error.message : String(error);
+        return result([`○ ${label} doctor unavailable (${truncateExternalDiagnostic(diagnostic)})`]);
     }
 }
 function openCodeLinks(homeDir) {

package/dist/help.js

@@ -7,46 +7,50 @@ const COMMANDS = [
         details: ['Options:', '  --cap <N|unlimited>  Set a per-participant activity cap (default unlimited).', '  --template <name>    Append a packaged activity guide.', '  --throttle <N>       Allow at most N public activities per minute.', '  -f, --force          Replace an existing artifact.'],
     },
     {
-        names: ['list', 'ls'], usage: '{command} [--depth N]', summary: 'List nearby squares below the current directory.', group: 'host',
-        details: ['Options:', '  --depth <N>  Descend through at most N directory levels (default 4; 0 scans only the current directory).'],
+        names: ['list', 'ls'], usage: '{command} [--depth N] [--limit N] [--after path]', summary: 'List nearby squares below the current directory.', group: 'host',
+        details: ['Options:', '  --depth <N>    Descend through at most N directory levels (default 4; maximum 16; 0 scans only the current directory).', '  --limit <N>    Show one page (default 20, maximum 100).', '  --after <path> Resume after a relative path from a previous page.'],
     },
     {
-        names: ['join'], usage: '--as <name> join [--last N | --all] [--kick]', usesSquare: true, group: 'participant',
+        names: ['join'], usage: '--as <name> join [--last N] [--kick]', usesSquare: true, group: 'participant',
         summary: 'Step into the square and read its current context.',
-        details: ['Options:', '  --last <N>  Show the last N public activities (default 10).', '  --all       Show the complete history.'],
+        details: ['Options:', '  --last <N>  Show the last N public activities (default 10, maximum 100).', '  --kick      End the standing participant and reclaim the name for this session.'],
     },
     {
-        names: ['express'], usage: '--as <name> express [-f|--force] [--no-wait] [--bell] [--reply <activity-id>] <activity | ->', usesSquare: true, group: 'participant',
+        names: ['express'], usage: '--as <name> express [-f|--force] [--no-wait] (--mention <name>... | --no-mention | --bell) [--reply <activity-id>] <activity | ->', usesSquare: true, group: 'participant',
         summary: 'Speak, gesture, or do both.',
-        details: ['Reach:', '  @name             Address someone in the square. They hear the body even without listen; everyone else sees you walk over.', '  bare              Lands in history even with no listener; listen opts someone into future bare delivery.', "  --bell            Call every participant's attention to this activity without a mention.", '', 'Options:', '  -f, --force       Express without first catching unread activity or attention etiquette.', '  --no-wait         If held or throttled, save a draft and return.', '  --reply <activity-id>   Mark this activity as a reply to an earlier activity (for example act/12).'],
+        details: ['Reach:', '  --mention <name>  Address one participant; repeat for multiple participants. The body stays unchanged.', '  --no-mention      Land a bare activity explicitly; listen opts someone into future bare delivery.', "  --bell            Call every participant's attention to this activity.", '', 'Options:', '  -f, --force       Express without first catching unread activity or attention etiquette.', '  --no-wait         If held or throttled, save a draft and return.', '  --reply <activity-id>   Mark this activity as a reply to an earlier activity (for example act/12).'],
     },
     { names: ['listen'], usage: '--as <name> listen <participant>', usesSquare: true, group: 'participant', summary: 'Turn an ear toward one participant\'s future bare says.' },
     { names: ['ignore'], usage: '--as <name> ignore <participant>', usesSquare: true, group: 'participant', summary: 'Ignore one participant\'s future mentions and bare says.' },
     { names: ['listening'], usage: '--as <name> listening', usesSquare: true, group: 'participant', summary: 'Show who you are turned toward.', details: ['Listening is future-only: the edge is fixed when a say lands; it never rewrites history.'] },
     {
-        names: ['catch'], usage: '--as <name> catch (--now | --idle <duration>) [--from <names>] [--mention [name]] [--replace]', usesSquare: true, group: 'participant',
+        names: ['catch'], usage: '--as <name> catch (--now | --idle <duration>) [--from <names>] [--mention] [--limit <count>] [--replace]', usesSquare: true, group: 'participant',
         summary: 'Catch directed conversation since you last looked.',
-        details: ['Modes:', '  --now             Catch up immediately.', '  --idle <duration> Wait for something relevant, or for quiet to last this long.', '', 'Attention:', '  Mentions arrive when you are addressed; bells arrive for everyone; bare says require listen.', '  listen and ignore are future-only and fixed when each say lands.', '', 'Filters:', '  --from <names>    Match only comma-separated participants.', '  --mention [name]  Match direct attention for a name, or your own name when omitted.', '', 'Recovery:', '  --replace         Replace another active catch for this participant.'],
+        details: ['Modes:', '  --now             Catch up immediately.', '  --idle <duration> Wait for something relevant, or for quiet to last this long.', '', 'Attention:', '  Mentions arrive when you are addressed; bells arrive for everyone; bare says require listen.', '  listen and ignore are future-only and fixed when each say lands.', '', 'Filters:', '  --from <names>    Match only comma-separated participants.', '  --mention         Match direct attention for your current participant (and bells).', '  --limit <count>   Return one page (default 10, maximum 100).', '', 'Recovery:', '  --replace         Replace another active catch for this participant.'],
     },
     { names: ['done'], usage: '--as <name> done [final | -]', usesSquare: true, group: 'participant', summary: 'Step out, optionally leaving a final note.' },
     {
-        names: ['stream'], usage: 'stream [--ndjson [--for <name>]]', usesSquare: true, hiddenFromIndex: true,
+        names: ['stream'], usage: 'stream [--ndjson [--for <name>] [--last <N> | --after <id>]]', usesSquare: true, hiddenFromIndex: true,
         summary: 'Follow activity without consuming participant presence.',
-        details: ['Options:', '  --ndjson       Emit one JSON event per line.', '  --for <name>   With --ndjson, emit notifications for one participant.'],
+        details: ['Options:', '  --ndjson       Emit one JSON event per line.', '  --for <name>   With --ndjson, emit notifications for one participant.', '  --last <N>     Emit the last N eligible activities first (default 10, maximum 100).', '  --after <id>   Resume after a canonical activity id (act/12).'],
     },
     {
-        names: ['inbox'], usage: 'inbox --for-session <session-id> [--json]', hiddenFromIndex: true,
-        summary: 'Inspect bounded machine-local notifications for a native session.',
-        details: ['Options:', '  --for-session <id>  Required harness session id.', '  --json              Emit structured JSON.'],
+        names: ['inbox'], usage: 'inbox --for-session <session-id> [--limit <N>] [--json]', hiddenFromIndex: true,
+        summary: 'Inspect a bounded machine-local notification snapshot for a native session.',
+        details: ['Options:', '  --for-session <id>  Required harness session id.', '  --limit <N>         Snapshot memberships (default 20, maximum 100).', '  --json              Emit the bounded snapshot as structured JSON.'],
     },
     { names: ['claude-hook', 'codex-hook'], usage: '{command}', summary: 'Present pending attention at one native agent boundary.', hiddenFromIndex: true },
     {
-        names: ['history'], usage: '[--as <name>] history [filters] [output]', usesSquare: true, group: 'participant',
+        names: ['history'], usage: 'history [filters] [output]', usesSquare: true, group: 'participant',
         summary: 'Read or search the archive without changing what you have caught.',
-        details: ['Filters:', '  --from <names>                  Match activities from participants.', '  --since <time>                  Match activities after a time.', '  --grep <regex> | --fixed <s>    Search activity ids, participants, and original bodies.', '  --mention <name>                Match direct attention for a participant.', '  --pending                       Match attention waiting for --as <name>.', '  --at <ids>                      Center on comma-separated activity ids; may repeat.', '  -B, -A, -C <N>                 Set non-negative context around every --at coordinate.', '  --before <id>                   Read the page immediately before an activity.', '  --after <id>                    Read the page immediately after an activity.', '', 'Results:', '  --limit <N>                     Page size (default 10).', '  --order <asc|desc>              Set display order (default oldest first).', '', 'Output:', '  --no-truncate  --json  --format <fields>', '  Bodies are previews by default; --no-truncate expands them. --as keeps participant perception.'],
+        details: ['Filters:', '  --from <names>                  Match activities from participants.', '  --since <time>                  Match activities after a time.', '  --grep <regex> | --fixed <s>    Search activity ids, participants, and original bodies.', '  --mention <name>                Match direct attention for a participant.', '  --at <ids>                      Center on comma-separated activity ids; may repeat.', '  -B, -A, -C <N>                 Set non-negative context around every --at coordinate.', '  --before <id>                   Read the page immediately before an activity.', '  --after <id>                    Read the page immediately after an activity.', '', 'Results:', '  --limit <N>                     Page size (default 10, maximum 100).', '  --order <asc|desc>              Set display order (default oldest first).', '', 'Output:', '  --no-truncate  --json  --format <fields>', '  One result shows its full body; multiple results use previews.', '  --no-truncate shows every original body.'],
     },
     { names: ['status'], usage: '[--as <name>] status', usesSquare: true, group: 'participant', summary: 'Show who is present and what happened most recently.' },
-    { names: ['participants'], usage: 'participants', usesSquare: true, group: 'host', summary: 'Show the full participant roster and current states.' },
+    {
+        names: ['participants'], usage: 'participants [--limit <count>]', usesSquare: true, group: 'host',
+        summary: 'Show the participant roster and current states.',
+        details: ['Options:', '  --limit <count>  Show the first count names in roster order (default 20, maximum 100).'],
+    },
     { names: ['hold'], usage: '--as <name> hold [reason | -]', usesSquare: true, group: 'participant', summary: 'Raise a hand and pause participant activity.' },
     { names: ['resume'], usage: '--as <name> resume', usesSquare: true, group: 'participant', summary: 'Lower the raised hand and resume activity.' },
     {
@@ -121,17 +125,22 @@ export function renderSubcommandHelp(command) {
 }
 export function helpRequest(rawArgs) {
     const args = [];
+    let hasExplicitName = false;
     for (let index = 0; index < rawArgs.length; index++) {
         const arg = rawArgs[index];
         if (arg === '--location' || arg === '--as') {
             const value = rawArgs[index + 1];
             if (value === undefined || value.startsWith('--'))
                 return undefined;
+            if (arg === '--as')
+                hasExplicitName = true;
             index++;
             continue;
         }
         args.push(arg);
     }
+    if (hasExplicitName && args[0] === 'history')
+        return undefined;
     if (isHelpFlag(args[0]))
         return {};
     if (args[0] === 'help') {

package/dist/inbox.d.ts

@@ -5,6 +5,8 @@ export interface PendingWaitOptions {
     excludeKeys?: ReadonlySet<string>;
     /** After a delivery failure, wait for a new state edge before retrying the same pending work. */
     skipImmediate?: boolean;
+    /** Reports whether a change wait has been established for a deferred retry. */
+    onChangeArmed?: (armed: boolean) => void;
 }
 export declare function sessionInbox(sessionId: string, env?: NodeJS.ProcessEnv): Promise<InboxMembership[]>;
 /** Wait for a bound square to produce a new pending notification without consuming it. */

package/dist/inbox.js

@@ -59,8 +59,10 @@ export async function waitForSessionPending(sessionId, timeoutMs, options = {},
         if (immediate.some((membership) => membership.notifications.length > 0))
             return immediate;
     }
-    if (timeoutMs <= 0 || options.signal?.aborted)
+    if (timeoutMs <= 0 || options.signal?.aborted) {
+        options.onChangeArmed?.(false);
         return [];
+    }
     const bindings = await projectSessionBindings({ hostLedger: hostLedgerForEnv(env), sessionId });
     const paths = [...new Set(bindings.map((binding) => binding.location))];
     let aborted = false;
@@ -77,7 +79,7 @@ export async function waitForSessionPending(sessionId, timeoutMs, options = {},
                     return undefined;
                 const current = withoutExcluded(await sessionInbox(sessionId, env), options.excludeKeys);
                 return current.some((membership) => membership.notifications.length > 0) ? current : undefined;
-            });
+            }, options.onChangeArmed);
             if (aborted || change.status === 'expired')
                 return [];
             if (change.status === 'ready')

package/dist/list.js

@@ -4,10 +4,15 @@ import { probeSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
 import { listPresentation } from './views.js';
 import { formatRelativeTime } from './time.js';
-import { participantIdentity } from './presentation.js';
+import { participantIdentity, quoteShell } from './presentation.js';
 const DEFAULT_LIST_DEPTH = 4;
+const MAX_LIST_DEPTH = 16;
+const DEFAULT_LIST_LIMIT = 20;
+const MAX_LIST_LIMIT = 100;
+const LIST_DISCOVERY_BUDGET = 10_000;
 const CONTEXT_PREVIEW_LINES = 2;
 const PARTICIPANT_PREVIEW_COUNT = 3;
+const DISPLAY_CHARACTER_LIMIT = 160;
 const LIST_SKIP_DIRS = new Set(['.git', 'node_modules', 'dist']);
 function contextLines(lines) {
     return lines.map((line) => line.trim()).filter(Boolean);
@@ -35,7 +40,11 @@ async function readSquareListItem(filePath, root) {
 }
 async function collectSquareList(root, maxDepth) {
     const items = [];
+    let examined = 0;
+    let stopped = false;
     async function walk(dir, depth) {
+        if (stopped)
+            return;
         let entries;
         try {
             entries = await fs.promises.readdir(dir, { withFileTypes: true });
@@ -44,10 +53,16 @@ async function collectSquareList(root, maxDepth) {
             // Directory vanished or became unreadable mid-walk — skip it, don't abort the scan.
             return;
         }
+        entries.sort((left, right) => left.name.localeCompare(right.name));
         for (const entry of entries) {
+            if (stopped)
+                return;
+            examined += 1;
+            if (examined === LIST_DISCOVERY_BUDGET)
+                stopped = true;
             const fullPath = path.join(dir, entry.name);
             if (entry.isDirectory()) {
-                if (depth < maxDepth && !LIST_SKIP_DIRS.has(entry.name))
+                if (!stopped && depth < maxDepth && !LIST_SKIP_DIRS.has(entry.name))
                     await walk(fullPath, depth + 1);
                 continue;
             }
@@ -59,46 +74,84 @@ async function collectSquareList(root, maxDepth) {
         }
     }
     await walk(root, 0);
-    return items.sort((a, b) => a.path.localeCompare(b.path));
+    return { items: items.sort((a, b) => a.path.localeCompare(b.path)), stopped };
+}
+function characterPreview(value) {
+    const characters = Array.from(value);
+    return characters.length <= DISPLAY_CHARACTER_LIMIT ? value : `${characters.slice(0, DISPLAY_CHARACTER_LIMIT - 1).join('')}…`;
 }
-function renderSquareList(items) {
-    if (items.length === 0)
-        return '(no squares found)\n';
+function renderSquareList(items, stopped, depth, limit, after) {
+    const page = after === undefined ? items : items.filter((item) => item.path.localeCompare(after) > 0);
+    const shownItems = page.slice(0, limit);
+    if (items.length === 0) {
+        return [`(no squares found)`, ...(stopped ? [`○ discovery stopped after examining ${LIST_DISCOVERY_BUDGET} filesystem entries; results may be incomplete`] : [])].join('\n') + '\n';
+    }
     const now = Date.now();
     const lines = ['squares'];
-    for (const item of items) {
-        lines.push(`${item.activities > 0 ? '●' : '○'} ${item.path} · ${formatRelativeTime(item.lastActiveAt, now)} · ${item.participants.length} in square · ${item.activities} activities`);
+    for (const item of shownItems) {
+        lines.push(`${item.activities > 0 ? '●' : '○'} ${characterPreview(item.path)} · ${formatRelativeTime(item.lastActiveAt, now)} · ${item.participants.length} in square · ${item.activities} activities`);
         const shownContext = item.context.slice(0, CONTEXT_PREVIEW_LINES);
         if (shownContext.length === 0) {
             lines.push('  context · (none)');
         }
         else {
-            shownContext.forEach((line, index) => lines.push(`  ${index === 0 ? 'context' : '       '} · ${line}`));
+            shownContext.forEach((line, index) => lines.push(`  ${index === 0 ? 'context' : '       '} · ${characterPreview(line)}`));
             const hiddenContext = item.context.length - shownContext.length;
             if (hiddenContext > 0)
                 lines.push(`          · … ${hiddenContext} more ${hiddenContext === 1 ? 'line' : 'lines'}`);
         }
         const shownParticipants = item.participants.slice(0, PARTICIPANT_PREVIEW_COUNT);
         const hiddenParticipants = item.participants.length - shownParticipants.length;
-        lines.push(`  participants · ${shownParticipants.length === 0 ? 'nobody' : shownParticipants.map(participantIdentity).join(' · ')}${hiddenParticipants > 0 ? ` · … ${hiddenParticipants} more` : ''}`);
+        lines.push(`  participants · ${shownParticipants.length === 0 ? 'nobody' : shownParticipants.map((participant) => participantIdentity(characterPreview(participant))).join(' · ')}${hiddenParticipants > 0 ? ` · … ${hiddenParticipants} more` : ''}`);
     }
+    const hiddenItems = page.length - shownItems.length;
+    if (hiddenItems > 0) {
+        const cursor = shownItems.at(-1)?.path;
+        lines.push(stopped ? '  … more squares' : `  … ${hiddenItems} more ${hiddenItems === 1 ? 'square' : 'squares'}`);
+        if (cursor !== undefined)
+            lines.push(`» square list --depth ${depth} --limit ${limit} --after ${quoteShell(cursor)}`);
+    }
+    if (stopped)
+        lines.push(`○ discovery stopped after examining ${LIST_DISCOVERY_BUDGET} filesystem entries; results may be incomplete`);
     return lines.join('\n') + '\n';
 }
-function parseMaxDepth(args, usage) {
-    if (args.length === 0)
-        return DEFAULT_LIST_DEPTH;
-    if (args.length !== 2 || args[0] !== '--depth' || !/^\d+$/.test(args[1])) {
-        usage();
-        return DEFAULT_LIST_DEPTH;
-    }
-    const depth = Number(args[1]);
-    if (!Number.isSafeInteger(depth)) {
-        usage();
-        return DEFAULT_LIST_DEPTH;
+function parseListOptions(args, usage) {
+    let depth = DEFAULT_LIST_DEPTH;
+    let limit = DEFAULT_LIST_LIMIT;
+    let after;
+    for (let index = 0; index < args.length; index += 2) {
+        const option = args[index];
+        const value = args[index + 1];
+        if (value === undefined || (option !== '--depth' && option !== '--limit' && option !== '--after')) {
+            usage();
+            return { depth, limit };
+        }
+        if (option === '--after') {
+            if (after !== undefined || value.length === 0 || path.isAbsolute(value)) {
+                usage();
+                return { depth, limit };
+            }
+            after = value;
+            continue;
+        }
+        if (!/^\d+$/.test(value)) {
+            usage();
+            return { depth, limit };
+        }
+        const parsed = Number(value);
+        if (!Number.isSafeInteger(parsed) || (option === '--depth' ? parsed > MAX_LIST_DEPTH : parsed === 0 || parsed > MAX_LIST_LIMIT)) {
+            usage();
+            return { depth, limit };
+        }
+        if (option === '--depth')
+            depth = parsed;
+        else
+            limit = parsed;
     }
-    return depth;
+    return { depth, limit, after };
 }
 export async function cmdListSquares(args, usage) {
-    const maxDepth = parseMaxDepth(args, usage);
-    process.stdout.write(renderSquareList(await collectSquareList(process.cwd(), maxDepth)));
+    const options = parseListOptions(args, usage);
+    const discovery = await collectSquareList(process.cwd(), options.depth);
+    process.stdout.write(renderSquareList(discovery.items, discovery.stopped, options.depth, options.limit, options.after));
 }

package/dist/model.d.ts

@@ -101,9 +101,6 @@ export interface ActivitiesOptions {
     beforeContext?: number;
     afterContext?: number;
     mention?: string;
-    /** Undelivered mention/bell items for viewer only (read-only; requires viewer). */
-    pending?: boolean;
-    viewer?: string;
     grep?: string;
     fixed?: string;
     order?: 'asc' | 'desc';
@@ -113,6 +110,7 @@ export interface ActivitiesOptions {
 export interface WatchOptions {
     participants?: string[];
     mention?: string;
+    limit?: number;
     idleMs?: number;
     replace?: boolean;
     now?: boolean;

package/dist/paseo-connection.js

@@ -46,6 +46,9 @@ function pidHost(env) {
 function isIpc(host) {
     return host !== undefined && (host.startsWith('unix://') || host.startsWith('pipe://'));
 }
+function supportsIpcHost(host) {
+    return process.platform !== 'win32' || !host.startsWith('unix://');
+}
 /** Match the host precedence used by the Paseo CLI for local daemon connections. */
 export function paseoDaemonHosts(env = process.env) {
     const explicit = normalizeHost(env.PASEO_HOST);
@@ -55,11 +58,11 @@ export function paseoDaemonHosts(env = process.env) {
     const listen = normalizeHost(env.PASEO_LISTEN);
     const pid = pidHost(env);
     const configured = configuredHost(env);
-    if (isIpc(listen))
+    if (isIpc(listen) && supportsIpcHost(listen))
         candidates.push(listen);
-    if (isIpc(pid))
+    if (isIpc(pid) && supportsIpcHost(pid))
         candidates.push(pid);
-    if (isIpc(configured))
+    if (isIpc(configured) && supportsIpcHost(configured))
         candidates.push(configured);
     if (configured !== undefined && !isIpc(configured) && configured !== '127.0.0.1:6767')
         candidates.push(configured);
@@ -73,6 +76,9 @@ function uriPassword(uri) {
 export function resolvePaseoDaemonTarget(host, env = process.env) {
     const passwordFromEnv = env.PASEO_PASSWORD?.trim() || undefined;
     if (host.startsWith('unix://') || host.startsWith('pipe://')) {
+        if (process.platform === 'win32' && host.startsWith('unix://')) {
+            throw new Error('Paseo Unix socket targets are unsupported on Windows; use pipe:// or tcp://.');
+        }
         const prefix = host.startsWith('unix://') ? 'unix://' : 'pipe://';
         const socketPath = expandHome(host.slice(prefix.length).trim());
         if (socketPath === '')

package/dist/paseo-state.d.ts

@@ -4,7 +4,10 @@ export interface PaseoAgent {
     status: string;
     cwd?: string;
 }
-export declare function discoverPaseoAgents(timeoutMs?: number): {
+export declare function discoverPaseoAgents(timeoutMs?: number, opts?: {
+    args?: string[];
+    bin?: string;
+}): {
     agents: PaseoAgent[];
     error?: string;
 };

package/dist/paseo-state.js

@@ -1,8 +1,8 @@
 import { execFileSync } from 'node:child_process';
 import { waitForPaseoToolBoundary } from './paseo-timeline.js';
-export function discoverPaseoAgents(timeoutMs = 5000) {
+export function discoverPaseoAgents(timeoutMs = 5000, opts = {}) {
     try {
-        const raw = execFileSync(process.env.SQUARE_PASEO_BIN || 'paseo', ['ls', '--global', '--json'], {
+        const raw = execFileSync(opts.bin ?? process.env.SQUARE_PASEO_BIN ?? 'paseo', [...(opts.args ?? []), 'ls', '--global', '--json'], {
             encoding: 'utf8',
             timeout: timeoutMs,
             stdio: ['ignore', 'pipe', 'pipe'],