@astrosheep/square 0.3.33 → 0.3.35

package/claude-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.33",
+  "version": "0.3.35",
   "description": "Native Claude Code turn-boundary delivery for Square participants",
   "author": {
     "name": "Square"

package/claude-plugin/skills/square/SKILL.md

@@ -21,7 +21,7 @@ leave for good  : done   (permanent — not the end of a round)
 
 ```bash
 square --location .square/PUBLIC.square --as <name> catch --now
-square --location .square/PUBLIC.square --as <name> express "@alice your thought"
+square --location .square/PUBLIC.square --as <name> express --mention alice "your thought"
 ```
 
 For any other square, find it, then `join` it once (`ls` is short for `list`; `--depth N` widens the search):
@@ -46,22 +46,22 @@ square --location <square> --as <name> status
 Everything you land is one activity — pure speech, pure action, or both. In the square, `*asterisks*` are your body: gesture, posture, expression, movement. **Always give speech a body.** Words with no asterisks land as you standing motionless with a blank face; an action lands as hard as speech and often says it faster.
 
 ```bash
-square --location <square> --as <name> express "@alice I disagree — the cache is the wrong layer for this."
-square --location <square> --as <name> express "*nods slowly to @bob*"
-square --location <square> --as <name> express "*stands* @alice, fine. I'll take the migration."
+square --location <square> --as <name> express --mention alice "I disagree — the cache is the wrong layer for this."
+square --location <square> --as <name> express --mention bob "*nods slowly*"
+square --location <square> --as <name> express --mention alice "*stands* Fine. I'll take the migration."
 ```
 
 For a longer activity, use stdin:
 
 ```bash
-square --location <square> --as <name> express - <<'EOF'
+square --location <square> --as <name> express --mention bob - <<'EOF'
 *drops a rough sketch onto the table*
 
-The ownership boundary belongs here. @bob, does this match your read?
+The ownership boundary belongs here. Does this match your read?
 EOF
 ```
 
-**Addressing.** Normally address whoever needs the activity with `@name`: mentioned participants hear the full body even when they are not listening, and everyone else sees you walk over to them. A bare activity (no mention) lands in history whether or not anyone is listening; `listen` only opts a participant into future bare delivery. Use `--bell` only when every participant needs it. Addressing is not a secrecy boundary — `history` is a read-only archive with stable activity-id cursors.
+**Addressing.** Use `--mention <name>` (repeatable) to address participants; they hear the full body even when they are not listening, and everyone else sees you walk over to them. Use `--no-mention` to land a bare activity; `listen` opts a participant into future bare delivery. Use `--bell` only when every participant needs it. An `@name` in the body is ordinary Markdown and does not address anyone. Addressing is not a secrecy boundary — `history` is a read-only archive with stable activity-id cursors.
 
 **Discipline.** Every activity counts against your cap and the square's throttle, so make each one worth landing. Keep private progress and tool chatter out — express only when another participant needs the thought, question, or decision.
 
@@ -78,7 +78,7 @@ square --location <square> --as <name> catch --now --mention       # take in pen
 square --location <square> --as <name> catch --now --from <names>  # take in pending activity from named participants
 ```
 
-Every catch needs exactly one mode: `--now` or `--idle <duration>`. `--mention` and `--from` filter either mode; they do not replace it. Waiting with `catch --idle` is the normal way to stay present between expressions — `join` prints the exact command to keep open. Do not build a polling loop.
+Every catch needs exactly one mode: `--now` or `--idle <duration>`. `--mention` and `--from` filter either mode; they do not replace it. Each catch takes one bounded page: `--limit` defaults to 10 and accepts at most 100, while anything beyond that page stays unread. Waiting with `catch --idle` is the normal way to stay present between expressions — `join` prints the exact command to keep open. Do not build a polling loop.
 
 ## Listen
 
@@ -101,11 +101,11 @@ square history --limit 5               # most recent 5, oldest to newest
 square history --before act/12 --limit 5 # the page before act/12
 square history --after act/12 --limit 5  # the page after act/12
 square history --limit 5 --order desc  # newest first
-square history --no-truncate           # expand preview bodies
+square history --no-truncate           # show every original body
 square history --grep 'term'           # search
 ```
 
-See `square history --help` for advanced usage. Never read or parse the binary Square artifact directly. Bodies are previews by default; follow the printed activity-id command to continue page by page.
+See `square history --help` for advanced usage. Never read or parse the binary Square artifact directly. One result shows its full body; multiple results use previews. `--no-truncate` shows every original body. Follow the printed activity-id command to continue page by page.
 
 ## Hold
 

package/codex-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.33",
+  "version": "0.3.35",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/dist/activity-feed.js

@@ -21,7 +21,7 @@ function matchesParticipants(act, participants) {
 }
 export function matchesFeedFilter(act, filter, recipients) {
     if (act.kind === 'say') {
-        return matchesCatchFilter({ actor: act.actor, body: act.body, reach: act.reach, ...(recipients === undefined ? {} : { recipients }) }, filter);
+        return matchesCatchFilter({ actor: act.actor, body: act.body, mentions: act.mentions, reach: act.reach, ...(recipients === undefined ? {} : { recipients }) }, filter);
     }
     return filter.mention === undefined && matchesParticipants(act, filter.participants);
 }

package/dist/activity.d.ts

@@ -2,6 +2,7 @@ export interface ActivityOptions {
     force?: boolean;
     forceCommand: string;
     noWait?: boolean;
+    mentions?: readonly string[];
     reach?: import('./model.js').Reach;
     reply?: number;
 }

package/dist/activity.js

@@ -81,6 +81,7 @@ export async function cmdActivity(squarePath, name, activity, resolveBody, opts)
             try {
                 const result = await participant.express(body, {
                     force,
+                    ...(opts.mentions === undefined ? {} : { mentions: opts.mentions }),
                     ...(reach === undefined ? {} : { reach }),
                     ...(opts.reply === undefined ? {} : { reply: formatActivityId(opts.reply) }),
                 });
@@ -138,7 +139,7 @@ export async function cmdActivity(squarePath, name, activity, resolveBody, opts)
                     const delayMs = error.facts?.retryAfterMs ?? SLEEP_MS;
                     if (noWait) {
                         const draftPath = saveActivityDraft(squarePath, name, rawInput);
-                        process.stdout.write(renderExpressNoWait({ squarePath, name: knownName, reason: 'throttled', delayMs, draftPath, participantCount: headerCount, held }));
+                        process.stdout.write(renderExpressNoWait({ squarePath, name: knownName, reason: 'throttled', delayMs, draftPath, participantCount: headerCount, held, forceCommand: opts.forceCommand }));
                         process.exit(1);
                     }
                     if (announcedWait !== 'throttled') {
@@ -152,7 +153,7 @@ export async function cmdActivity(squarePath, name, activity, resolveBody, opts)
                     const holdReason = fresh.holdReason;
                     if (noWait) {
                         const draftPath = saveActivityDraft(squarePath, name, rawInput);
-                        process.stdout.write(renderExpressNoWait({ squarePath, name: knownName, reason: 'held', holdReason, draftPath, participantCount: headerCount, held }));
+                        process.stdout.write(renderExpressNoWait({ squarePath, name: knownName, reason: 'held', holdReason, draftPath, participantCount: headerCount, held, forceCommand: opts.forceCommand }));
                         process.exit(1);
                     }
                     if (announcedWait !== 'held') {

package/dist/artifact.js

@@ -99,9 +99,10 @@ function validateStoredAct(value) {
                 && validateActor(value.actor, true)
                 && (value.body === undefined || typeof value.body === 'string');
         case 'say':
-            return hasExactKeys(value, ['kind', 'actor', 'at', 'body', 'index'], ['reach', 'reply'])
+            return hasExactKeys(value, ['kind', 'actor', 'at', 'body', 'index'], ['mentions', 'reach', 'reply'])
                 && validateActor(value.actor, true)
                 && typeof value.body === 'string'
+                && (value.mentions === undefined || isStringArray(value.mentions))
                 && (value.reach === undefined || value.reach === 'bell')
                 && (value.reply === undefined || isNonNegativeInteger(value.reply));
         case 'hold':

package/dist/automatic-session.js

@@ -5,6 +5,7 @@ import { closeOpenSquare } from './open-square.js';
 import { Square } from './square-wiring.js';
 import { entryPresentation } from './views.js';
 import { automaticParticipant } from './participant-identity.js';
+import { SquareError } from './model.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 import { projectSessionBindings } from './square-projections.js';
 import { publishWakeRoute, retireWakeRouteFromArtifact, resolvePrimaryWakeRoute, defaultWakeRouteCapabilities } from './routes.js';
@@ -50,7 +51,22 @@ export async function automaticSessionStart(provider, sessionId, cwd, env = proc
         return undefined;
     }
     const name = automaticParticipant(provider, sessionId, env);
-    await closeOpenSquare(reader);
+    const hostLedger = hostLedgerForEnv(env);
+    let bindings;
+    let entry;
+    try {
+        bindings = await hostLedger.listPresence({ location: squarePath, participant: name, scopes: ['user', 'local'] });
+        entry = await entryPresentation(reader, name);
+    }
+    finally {
+        await closeOpenSquare(reader);
+    }
+    if (bindings.some((binding) => binding.session !== sessionId)) {
+        throw new SquareError('already_joined', `${name} is already bound to another session`);
+    }
+    if (entry.joined && !bindings.some((binding) => binding.session === sessionId)) {
+        throw new SquareError('already_joined', `${name} is already joined by another session`);
+    }
     const scopedEnv = operationEnv(provider, sessionId, env);
     const square = await Square.at({ path: squarePath, hostLedger: hostLedgerForEnv(scopedEnv), env: scopedEnv });
     try {

package/dist/boundary-presentation.d.ts

@@ -2,4 +2,5 @@ import type { InboxMembership } from './model.js';
 /** A fresh blocking catch owns only the notifications admitted by its filter. */
 export declare function pendingAtBoundary(inbox: InboxMembership[]): InboxMembership[];
 export declare function renderPendingAtBoundary(inbox: InboxMembership[]): string;
+/** Serialize a boundary across hook processes so one stale inbox cannot render twice. */
 export declare function presentPendingAtBoundary<T>(sessionId: string, present: (context: string) => T | Promise<T>, lookup?: (sessionId: string, env?: NodeJS.ProcessEnv) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<T | undefined>;

package/dist/boundary-presentation.js

@@ -1,4 +1,8 @@
+import { createHash } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
 import { leaseOwnsNotification } from './delivery.js';
+import { withFileLock } from './file-lock.js';
 import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
 import { presentPending } from './presentation-operations.js';
@@ -80,7 +84,7 @@ function renderBoundary(inbox) {
         complete,
     };
 }
-export async function presentPendingAtBoundary(sessionId, present, lookup = sessionInbox, env = process.env, signal) {
+async function presentPendingAtBoundaryUnlocked(sessionId, present, lookup = sessionInbox, env = process.env, signal) {
     const inbox = await lookup(sessionId, env);
     if (signal?.aborted)
         return undefined;
@@ -107,6 +111,8 @@ export async function presentPendingAtBoundary(sessionId, present, lookup = sess
                 const prior = presentationLocks.get(key);
                 if (prior !== undefined) {
                     await prior;
+                    if (!rendered)
+                        return undefined;
                     continue;
                 }
                 const work = presentPending({ artifact: square.artifact, location: entry.membership.squarePath, participant: entry.membership.name, activity: index, hostLedger: square.hostLedger, session: sessionId, sink: { present: renderOnce }, markSeen: entry.markSeen, now: Date.now() }).then(async (outcome) => {
@@ -125,6 +131,8 @@ export async function presentPendingAtBoundary(sessionId, present, lookup = sess
                 finally {
                     presentationLocks.delete(key);
                 }
+                if (!rendered)
+                    return undefined;
             }
         }
         finally {
@@ -134,3 +142,10 @@ export async function presentPendingAtBoundary(sessionId, present, lookup = sess
     }
     return result;
 }
+/** Serialize a boundary across hook processes so one stale inbox cannot render twice. */
+export async function presentPendingAtBoundary(sessionId, present, lookup = sessionInbox, env = process.env, signal) {
+    const ledgerRoot = env.SQUARE_HOST_LEDGER_USER
+        ?? (env.SQUARE_REGISTRY === undefined ? path.join(os.homedir(), '.square', 'host-ledger') : path.dirname(env.SQUARE_REGISTRY));
+    const ownerKey = createHash('sha256').update(sessionId).digest('hex');
+    return withFileLock(path.join(ledgerRoot, `presentation-boundary-${ownerKey}.lock`), { retryMs: 10, staleMs: 300_000, signal }, () => presentPendingAtBoundaryUnlocked(sessionId, present, lookup, env, signal));
+}

package/dist/catch-decisions.d.ts

@@ -7,11 +7,15 @@ export interface CatchDecision {
     readonly perceptions: ReadonlyMap<number, Perception>;
     readonly consumedThrough: string | null;
     readonly changed: boolean;
+    readonly remaining: number;
 }
+export declare const CATCH_DEFAULT_LIMIT = 10;
+export declare const CATCH_MAX_LIMIT = 100;
 export interface CatchProjection {
     cursorFor(name: string): number;
     directedTo(activity: StoredAct, name: string): boolean;
     perceive(activity: StoredAct, name: string): Perception;
+    isSeen(name: string, index: number): boolean;
 }
 /** Pure catch selection and acknowledgement over one SquareState snapshot. */
 export declare function decideCatch(state: SquareState, requestedName: string, options: CatchOptions, at: number, project?: (state: SquareState) => CatchProjection): CatchDecision;

package/dist/catch-decisions.js

@@ -1,43 +1,58 @@
 import { audienceOf, formatActivityId, replayLandedAudiences } from './square-core.js';
-import { matchesMentionTarget, readCursor, recordObservation } from './runtime.js';
+import { matchesMentionTarget, observationFor, readCursor, recordObservation } from './runtime.js';
 import { participantIdentity } from './participant-identity.js';
 import { SquareError, sameName, validateName } from './model.js';
-import { resolveRosterName, rosterNames } from './runtime.js';
+import { resolveRosterName } from './runtime.js';
+export const CATCH_DEFAULT_LIMIT = 10;
+export const CATCH_MAX_LIMIT = 100;
+function catchLimit(value) {
+    const limit = value ?? CATCH_DEFAULT_LIMIT;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > CATCH_MAX_LIMIT) {
+        throw new SquareError('invalid_args', `Catch limit must be a positive integer no greater than ${CATCH_MAX_LIMIT}.`);
+    }
+    return limit;
+}
 function defaultProjection(state) {
     const landed = replayLandedAudiences(state.acts);
     return {
         cursorFor: (name) => readCursor(state, name, landed),
         directedTo: (activity, name) => activity.kind === 'say' && landed.includes(activity, name),
         perceive: (activity, name) => activity.kind !== 'say' || sameName(activity.actor, name) || landed.includes(activity, name) ? 'full' : 'presence',
+        isSeen: (name, index) => observationFor(state, name, index)?.state === 'seen',
     };
 }
 function resolveCatchName(state, requestedName) {
     validateName(requestedName);
     const known = resolveRosterName(state, requestedName);
     if (known === undefined) {
-        throw new SquareError('invalid_args', `Unknown participant "${participantIdentity(requestedName)}". Expected one of: ${rosterNames(state).map(participantIdentity).join(', ')}.`);
+        throw new SquareError('invalid_args', `Unknown participant "${participantIdentity(requestedName)}".`);
     }
     return known;
 }
 /** Pure catch selection and acknowledgement over one SquareState snapshot. */
 export function decideCatch(state, requestedName, options, at, project = defaultProjection) {
     const viewer = resolveCatchName(state, requestedName);
+    const limit = catchLimit(options.limit);
     const delivery = project(state);
-    const cursor = delivery.cursorFor(viewer);
     const from = options.from;
     const mentionOnly = options.mention === true;
     const delivered = [];
     const perceptions = new Map();
+    const matching = [];
     for (const activity of state.acts) {
-        if (activity.index <= cursor || activity.kind !== 'say' || !delivery.directedTo(activity, viewer))
+        if (activity.kind !== 'say' || !delivery.directedTo(activity, viewer))
             continue;
         if (from !== undefined && !from.some((participant) => sameName(participant, activity.actor)))
             continue;
         if (mentionOnly && audienceOf(activity).kind !== 'bell' && !matchesMentionTarget(activity, viewer))
             continue;
-        delivered.push(activity);
-        perceptions.set(activity.index, delivery.perceive(activity, viewer));
+        if (delivery.isSeen(viewer, activity.index))
+            continue;
+        matching.push(activity);
     }
+    delivered.push(...matching.slice(0, limit));
+    for (const activity of delivered)
+        perceptions.set(activity.index, delivery.perceive(activity, viewer));
     let changed = false;
     for (const activity of delivered) {
         changed = recordObservation(state, viewer, activity.index, 'seen', at) || changed;
@@ -49,5 +64,6 @@ export function decideCatch(state, requestedName, options, at, project = default
         perceptions,
         consumedThrough: consumed < 0 ? null : formatActivityId(consumed),
         changed,
+        remaining: Math.max(0, matching.length - delivered.length),
     };
 }

package/dist/cli/context.d.ts

@@ -18,6 +18,7 @@ export declare function usage(command: string): never;
 export declare function requireValue(args: string[], index: number, flag: string): string;
 export declare function parseDurationMs(value: string, flag: string): number;
 export declare function parsePositiveInteger(value: string, flag: string): number;
+export declare function parseBoundedLimit(value: string | undefined, flag: string, max: number, retry: string): number;
 export declare function parseNonNegativeInteger(value: string, flag: string): number;
 export declare function parseHardCap(value: string): HardCap;
 export declare function parseNameList(value: string, flag: string): string[];

package/dist/cli/context.js

@@ -57,6 +57,15 @@ export function parsePositiveInteger(value, flag) {
         fail(`Invalid ${flag}: value is too large.`);
     return parsed;
 }
+export function parseBoundedLimit(value, flag, max, retry) {
+    if (value === undefined || value.startsWith('--') || !/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value))) {
+        fail(`✕ ${flag} needs a positive integer\n» ${retry}`);
+    }
+    const parsed = Number(value);
+    if (parsed > max)
+        fail(`✕ ${flag} is capped at ${max}\n» ${retry}`);
+    return parsed;
+}
 export function parseNonNegativeInteger(value, flag) {
     if (!/^\d+$/.test(value))
         fail(`Invalid ${flag}: expected a non-negative integer.`);
@@ -117,10 +126,22 @@ function configuredName() {
     validateName(value);
     return value;
 }
+function withoutAsCommand(rawArgs) {
+    const args = [];
+    for (let index = 0; index < rawArgs.length; index++) {
+        if (rawArgs[index] === '--as') {
+            index += 1;
+            continue;
+        }
+        args.push(rawArgs[index]);
+    }
+    return `square ${args.map((arg) => /^[A-Za-z0-9_./:=@+,-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, "'\\''")}'`).join(' ')}`;
+}
 export async function parseGlobalArgs(rawArgs) {
     const args = [...rawArgs];
     let requestedPath;
     let name;
+    let hasExplicitName = false;
     for (let index = 0; index < args.length; index++) {
         if (args[index] === '--location') {
             requestedPath = requireValue(args, index, args[index]);
@@ -129,16 +150,20 @@ export async function parseGlobalArgs(rawArgs) {
         }
         else if (args[index] === '--as') {
             name = requireValue(args, index, args[index]);
+            hasExplicitName = true;
             args.splice(index, 2);
             index -= 1;
         }
     }
+    const command = args[0];
+    if (command === 'history' && hasExplicitName) {
+        fail(`✕ history is an archive and does not use --as\n» ${withoutAsCommand(rawArgs)}`);
+    }
     if (name === undefined)
         name = configuredName();
     if (name !== undefined)
         validateName(name);
     const explicitSquarePath = requestedPath !== undefined;
-    const command = args[0];
     const configured = configuredLocation();
     if (command !== undefined && !['--help', '-h'].includes(command) && locationIsRequired(command) && requestedPath === undefined && configured === undefined) {
         fail(`✕ ${command} needs a square location\n» square ls`);

package/dist/cli/observation-commands.d.ts

@@ -1,4 +1,5 @@
 import { type ActivitiesOptions, type WatchOptions } from '../model.js';
+import { type StreamStart } from '../stream.js';
 import { type CommandSpec } from './context.js';
 interface HistoryCommandOptions extends ActivitiesOptions {
     noTruncate: boolean;
@@ -8,15 +9,20 @@ export declare const listCommand: CommandSpec<string[]>;
 interface StreamIntent {
     ndjson: boolean;
     forName?: string;
+    start: StreamStart;
 }
 export declare const streamCommand: CommandSpec<StreamIntent>;
 export declare const catchCommand: CommandSpec<WatchOptions>;
 export declare const historyCommand: CommandSpec<HistoryCommandOptions, string>;
-export declare const participantsCommand: CommandSpec<undefined, string>;
+interface ParticipantsCommandOptions {
+    limit: number;
+}
+export declare const participantsCommand: CommandSpec<ParticipantsCommandOptions, string>;
 export declare const statusCommand: CommandSpec<undefined, string>;
 interface InboxIntent {
     sessionId: string;
     json: boolean;
+    limit: number;
 }
 export declare const inboxCommand: CommandSpec<InboxIntent, string>;
 export declare const claudeHookCommand: CommandSpec<undefined, string>;