@astrosheep/square 0.3.14 → 0.3.16

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

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

package/dist/activity-feed.d.ts

@@ -4,11 +4,10 @@ export interface ActivityFeedFilter {
     mention?: string;
 }
 export declare function actDelta(acts: StoredAct[], cursor: number): StoredAct[];
-/** Public cursor changes plus directed receipts that remain pending behind it. */
+/** Visible activities after the participant's derived continuous-seen prefix. */
 export declare function deliveryDelta(squareState: SquareState, name: string): StoredAct[];
 export declare function peerRoomChanges(delta: StoredAct[], name: string): RoomChangeAct[];
 export declare function peerPublicActs(delta: StoredAct[], name: string): PublicAct[];
-export declare function matchesFeedFilter(act: StoredAct, filter: ActivityFeedFilter): boolean;
+export declare function matchesFeedFilter(act: StoredAct, filter: ActivityFeedFilter, recipients?: readonly string[]): boolean;
 export declare function filteredPeerActivities(delta: StoredAct[], name: string, filter: ActivityFeedFilter): PublicAct[];
 export declare function filteredRoomChanges(delta: StoredAct[], name: string, filter: ActivityFeedFilter): RoomChangeAct[];
-export declare function ackPeerDelta(squareState: SquareState, name: string, delta: StoredAct[], at?: number): boolean;

package/dist/activity-feed.js

@@ -1,18 +1,12 @@
 import { sameName } from './model.js';
-import { advanceCursor, latestActIndex, readCursor } from './runtime.js';
-import { deriveDeliveryModel, matchesCatchFilter } from './delivery.js';
+import { readCursor } from './runtime.js';
+import { matchesCatchFilter } from './delivery.js';
 export function actDelta(acts, cursor) {
     return acts.filter((act) => act.index > cursor);
 }
-/** Public cursor changes plus directed receipts that remain pending behind it. */
+/** Visible activities after the participant's derived continuous-seen prefix. */
 export function deliveryDelta(squareState, name) {
-    const items = actDelta(squareState.acts, readCursor(squareState, name));
-    const seen = new Set(items.map((act) => act.index));
-    for (const notification of deriveDeliveryModel(squareState).pendingFor(name)) {
-        if (!seen.has(notification.item.index))
-            items.push(notification.item);
-    }
-    return items.sort((a, b) => a.index - b.index);
+    return actDelta(squareState.acts, readCursor(squareState, name));
 }
 export function peerRoomChanges(delta, name) {
     return delta.filter((act) => act.actor !== undefined && !sameName(act.actor, name) && act.kind !== 'say' && act.kind !== 'read');
@@ -23,9 +17,9 @@ export function peerPublicActs(delta, name) {
 function matchesParticipants(act, participants) {
     return participants === undefined || (act.actor !== undefined && participants.some((participant) => sameName(participant, act.actor)));
 }
-export function matchesFeedFilter(act, filter) {
+export function matchesFeedFilter(act, filter, recipients) {
     if (act.kind === 'say') {
-        return matchesCatchFilter({ actor: act.actor, body: act.body, reach: act.reach }, filter);
+        return matchesCatchFilter({ actor: act.actor, body: act.body, reach: act.reach, ...(recipients === undefined ? {} : { recipients }) }, filter);
     }
     return filter.mention === undefined && matchesParticipants(act, filter.participants);
 }
@@ -39,6 +33,3 @@ export function filteredRoomChanges(delta, name, filter) {
         return [];
     return peerRoomChanges(delta, name).filter((act) => matchesParticipants(act, filter.participants));
 }
-export function ackPeerDelta(squareState, name, delta, at) {
-    return advanceCursor(squareState, name, latestActIndex([...peerPublicActs(delta, name), ...peerRoomChanges(delta, name)]), at);
-}

package/dist/activity.js

@@ -87,7 +87,7 @@ export async function cmdActivity(squarePath, name, activity, resolveBody, opts)
                 const held = fresh.held;
                 const ownActCount = fresh.ownActivityCount;
                 const hasPending = pendingPublic.length > 0 || pendingRoomChanges.length > 0;
-                const pending = hasPending ? `\n\n${renderPendingFeed([...fresh.activities], [...pendingPublic], [...pendingRoomChanges], knownName)}` : '';
+                const pending = hasPending ? `\n\n${renderPendingFeed([...fresh.activities], [...pendingPublic], [...pendingRoomChanges], knownName, fresh.state)}` : '';
                 const hint = expressHintLine(ownActCount);
                 const confirmation = `● heads turn your way — #${ownActCount}`;
                 const withHint = hint ? `${confirmation}\n${hint}` : confirmation;

package/dist/artifact.js

@@ -33,18 +33,12 @@ function isNonblankString(value) {
 function isStringArray(value) {
     return Array.isArray(value) && value.every((item) => typeof item === 'string');
 }
-function validateReadCursor(value) {
+function validateObservation(value) {
     return isObject(value)
-        && hasExactKeys(value, ['consumedThroughIndex', 'updatedAt'])
-        && Number.isSafeInteger(value.consumedThroughIndex)
-        && value.consumedThroughIndex >= -1
-        && isFiniteNumber(value.updatedAt);
-}
-function validateDeliveryReceipt(value) {
-    return isObject(value)
-        && hasExactKeys(value, ['status', 'at'])
-        && value.status === 'delivered'
-        && isFiniteNumber(value.at);
+        && hasExactKeys(value, ['state', 'at'], ['ownerId'])
+        && (value.state === 'notified' || value.state === 'seen')
+        && isFiniteNumber(value.at)
+        && (value.ownerId === undefined || isNonblankString(value.ownerId));
 }
 function validateWatchLease(value) {
     if (!isObject(value)
@@ -100,25 +94,18 @@ function parseNotifyLeaseKey(key) {
 }
 function validateRuntime(value) {
     if (!isObject(value)
-        || !hasExactKeys(value, ['nextActIndex', 'cursors', 'deliveryReceipts', 'leases', 'notifyLeases'])
+        || !hasExactKeys(value, ['nextActIndex', 'observations', 'leases', 'notifyLeases'])
         || !isNonNegativeInteger(value.nextActIndex)
-        || !validateRecord(value.cursors, validateReadCursor)
+        || !validateRecord(value.observations, (candidate) => isObject(candidate) && Object.entries(candidate).every(([id, observation]) => parseActivityId(id) !== undefined && validateObservation(observation)))
         || !validateRecord(value.leases, validateWatchLease)
-        || !validateRecord(value.notifyLeases, validateNotifyLease)
-        || !isObject(value.deliveryReceipts))
+        || !validateRecord(value.notifyLeases, validateNotifyLease))
         return false;
-    return Object.entries(value.deliveryReceipts).every(([name, receipts]) => name.length > 0
-        && isObject(receipts)
-        && Object.entries(receipts).every(([id, receipt]) => parseActivityId(id) !== undefined && validateDeliveryReceipt(receipt)));
+    return true;
 }
 function validateAssignedRuntimeReferences(runtime) {
     const bound = runtime.nextActIndex;
-    for (const cursor of Object.values(runtime.cursors)) {
-        if (cursor.consumedThroughIndex !== -1 && cursor.consumedThroughIndex >= bound)
-            return 'future';
-    }
-    for (const receipts of Object.values(runtime.deliveryReceipts)) {
-        for (const id of Object.keys(receipts)) {
+    for (const observations of Object.values(runtime.observations)) {
+        for (const id of Object.keys(observations)) {
             const index = parseActivityId(id);
             if (index === undefined)
                 return 'malformed';
@@ -167,6 +154,11 @@ function validateStoredAct(value) {
             return hasExactKeys(value, ['kind', 'actor', 'at', 'through', 'index'])
                 && validateActor(value.actor, true)
                 && isNonNegativeInteger(value.through);
+        case 'listen':
+        case 'ignore':
+            return hasExactKeys(value, ['kind', 'actor', 'target', 'at', 'index'])
+                && validateActor(value.actor, true)
+                && validateActor(value.target, true);
         default:
             return false;
     }
@@ -257,8 +249,7 @@ function decodeEnvelope(bytes, magic) {
 export function emptyRuntimeState(nextActIndex = 0) {
     return {
         nextActIndex,
-        cursors: {},
-        deliveryReceipts: {},
+        observations: {},
         leases: {},
         notifyLeases: {},
     };

package/dist/attention-presentation.d.ts

@@ -0,0 +1,13 @@
+import type { DirectedNotificationRoute } from './model.js';
+export declare const ATTENTION_BODY_MAX = 120;
+export interface AttentionPreview {
+    squarePath: string;
+    actIndex: number;
+    recipient: string;
+    actor: string;
+    route: DirectedNotificationRoute;
+    body: string;
+}
+export declare function previewAttentionBody(body: string): string;
+export declare function displayAttentionPath(squarePath: string): string;
+export declare function renderAttentionPreview(attention: AttentionPreview): string;

package/dist/attention-presentation.js

@@ -0,0 +1,22 @@
+import { homedir } from 'node:os';
+import { notificationMessageId } from './delivery.js';
+import { participantIdentity } from './presentation.js';
+export const ATTENTION_BODY_MAX = 120;
+export function previewAttentionBody(body) {
+    const compact = body.replace(/\r\n/g, '\n');
+    if (compact.length <= ATTENTION_BODY_MAX)
+        return compact;
+    return `${compact.slice(0, ATTENTION_BODY_MAX).trimEnd()}\n… [truncated; run catch --now]`;
+}
+export function displayAttentionPath(squarePath) {
+    return squarePath.startsWith(homedir())
+        ? `~${squarePath.slice(homedir().length)}`
+        : squarePath;
+}
+export function renderAttentionPreview(attention) {
+    const attentionKind = attention.route === 'bell' ? 'bell' : 'attention';
+    return [
+        `${notificationMessageId(attention.squarePath, attention.actIndex)} · ${displayAttentionPath(attention.squarePath)}: ${participantIdentity(attention.recipient)} from ${participantIdentity(attention.actor)} (${attentionKind})`,
+        previewAttentionBody(attention.body),
+    ].join('\n');
+}

package/dist/automatic-session.js

@@ -5,7 +5,7 @@ import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
 import { Square } from './square-wiring.js';
 import { entryPresentation } from './views.js';
-import { canonicalSquarePath, lookupSession, lookupSessionBindings, recordSessionDone, recordSessionJoin } from './registry.js';
+import { canonicalSquarePath, lookupSessionBindings, recordSessionDone, recordSessionJoin } from './registry.js';
 import { participantIdentity, renderAmbientEvent } from './presentation.js';
 import { validateName } from './model.js';
 const providerEnv = {
@@ -39,16 +39,13 @@ export async function automaticSessionStart(provider, sessionId, cwd, env = proc
         return undefined;
     }
     const name = automaticParticipant(provider, sessionId, env);
-    const bindings = lookupSession(sessionId);
-    const before = await entryPresentation(reader, name);
-    if (bindings.some((binding) => canonicalSquarePath(binding.squarePath) === canonicalSquarePath(squarePath) && binding.name === name) && before.joined) {
-        await closeOpenSquare(reader);
-        return undefined;
-    }
+    const alreadyBound = lookupSessionBindings(sessionId).some((binding) => canonicalSquarePath(binding.squarePath) === canonicalSquarePath(squarePath) && binding.name === name);
     await closeOpenSquare(reader);
     const square = await Square.at({ path: squarePath });
     try {
-        await square.join(name);
+        const implicit = await square.implicitJoin(name);
+        if (implicit.state === 'done' || (implicit.state === 'active' && alreadyBound))
+            return undefined;
         const channel = provider === 'claude' ? 'claude-code' : provider;
         recordSessionJoin(sessionId, name, squarePath, channel, { ...env, [providerEnv[provider]]: sessionId });
         const afterSquare = await openSquare(squarePath);
@@ -57,6 +54,7 @@ export async function automaticSessionStart(provider, sessionId, cwd, env = proc
             now: Date.now(),
             preview: 200,
             actNumber: event.kind === 'say' ? after.sayNumbers[event.index] : undefined,
+            squareState: after.state,
         })).filter(Boolean).join('\n\n');
         return [`You joined the public square as ${participantIdentity(name)}.`, after.scene, after.context ? `context\n${after.context}` : '', activity ? `recent activity\n${activity}` : ''].filter(Boolean).join('\n\n');
     }

package/dist/boundary-presentation.js

@@ -1,8 +1,10 @@
-import { leaseOwnsNotification, notificationMessageId } from './delivery.js';
+import { leaseOwnsNotification } from './delivery.js';
 import { sessionInbox } from './inbox.js';
-import { participantCommandPrefix, participantIdentity } from './presentation.js';
+import { notificationMessageId } from './delivery.js';
+import { markBoundarySeen } from './square-wiring.js';
+import { renderAttentionPreview } from './attention-presentation.js';
+import { participantCommandPrefix } from './presentation.js';
 import { presentOnce } from './presented.js';
-const BODY_MAX = 200;
 const CONTEXT_MAX = 1200;
 function pendingCount(inbox) {
     return inbox.reduce((total, membership) => total + membership.notifications.length, 0);
@@ -16,17 +18,11 @@ export function pendingAtBoundary(inbox) {
             return membership;
         return {
             ...membership,
-            notifications: membership.notifications.filter((notification) => !leaseOwnsNotification(lease, notification)),
+            notifications: membership.notifications.filter((notification) => !leaseOwnsNotification(lease, { ...notification, recipient: membership.name })),
         };
     })
         .filter((membership) => membership.notifications.length > 0);
 }
-function bodyPreview(body) {
-    const compact = body.replace(/\r\n/g, '\n');
-    if (compact.length <= BODY_MAX)
-        return compact;
-    return `${compact.slice(0, BODY_MAX).trimEnd()}\n… [truncated; run catch --now]`;
-}
 export function renderPendingAtBoundary(inbox) {
     const count = pendingCount(inbox);
     const noun = count === 1 ? 'notification' : 'notifications';
@@ -41,10 +37,15 @@ export function renderPendingAtBoundary(inbox) {
     for (const [index, entry] of queued.entries()) {
         const { membership, notification } = entry;
         const command = `${participantCommandPrefix(membership.squarePath, membership.name)} catch --now`;
-        const id = notificationMessageId(membership.squarePath, notification.actIndex);
         const block = [
-            `${id} · ${membership.squarePath}: ${participantIdentity(membership.name)} from ${participantIdentity(notification.actor)} (${notification.route})`,
-            bodyPreview(notification.body),
+            renderAttentionPreview({
+                squarePath: membership.squarePath,
+                actIndex: notification.actIndex,
+                recipient: membership.name,
+                actor: notification.actor,
+                route: notification.route,
+                body: notification.body,
+            }),
             `Ack with: ${command}`,
         ].join('\n');
         const omittedAfter = omitted + queued.length - index - 1;
@@ -74,5 +75,25 @@ export function renderPendingAtBoundary(inbox) {
 }
 export async function presentPendingAtBoundary(sessionId, present, lookup = sessionInbox, env = process.env) {
     const inbox = await lookup(sessionId);
-    return presentOnce(sessionId, () => pendingAtBoundary(inbox), (inbox) => present(renderPendingAtBoundary(inbox)), env);
+    let deliveredInbox;
+    let deliveredContext;
+    const result = presentOnce(sessionId, () => pendingAtBoundary(inbox), (inbox) => {
+        const context = renderPendingAtBoundary(inbox);
+        deliveredInbox = inbox;
+        deliveredContext = context;
+        return present(context);
+    }, env);
+    if (result !== undefined && deliveredInbox !== undefined && deliveredContext !== undefined) {
+        await markCompleteBoundaryObservations(deliveredInbox, deliveredContext);
+    }
+    return result;
+}
+async function markCompleteBoundaryObservations(inbox, context) {
+    for (const membership of inbox) {
+        const complete = membership.notifications
+            .filter((notification) => context.includes(notificationMessageId(membership.squarePath, notification.actIndex)) && notification.body.length <= 120)
+            .map((notification) => notification.actIndex);
+        if (complete.length > 0)
+            await markBoundarySeen(membership.squarePath, membership.name, membership.ownerId, complete);
+    }
 }

package/dist/claude-hook.js

@@ -12,11 +12,12 @@ export async function runClaudeHookAsync(inputText, env = process.env) {
     if (input === null || typeof input !== 'object')
         return '';
     const value = input;
-    if (typeof value.session_id !== 'string' || typeof value.cwd !== 'string')
+    if (typeof value.session_id !== 'string')
         return runClaudeHook(inputText, env);
     if (value.hook_event_name === 'SessionStart' || value.hook_event_name === 'SessionResume') {
+        const cwd = typeof value.cwd === 'string' ? value.cwd : process.cwd();
         try {
-            const context = await automaticSessionStart('claude', value.session_id, value.cwd, env);
+            const context = await automaticSessionStart('claude', value.session_id, cwd, env);
             return context === undefined ? '' : `${JSON.stringify({ hookSpecificOutput: { hookEventName: value.hook_event_name, additionalContext: context } })}\n`;
         }
         catch {
@@ -24,8 +25,9 @@ export async function runClaudeHookAsync(inputText, env = process.env) {
         }
     }
     if (value.hook_event_name === 'SessionEnd') {
+        const cwd = typeof value.cwd === 'string' ? value.cwd : process.cwd();
         try {
-            await automaticSessionEnd('claude', value.session_id, value.cwd, env);
+            await automaticSessionEnd('claude', value.session_id, cwd, env);
         }
         catch { /* end remains bounded */ }
         return '';

package/dist/cli/context.d.ts

@@ -1,7 +1,6 @@
 import { type HardCap } from '../model.js';
-export declare const DEFAULT_SQUARE_PATH = ".square/SQUARE.square";
 export interface CommandContext {
-    squarePath: string;
+    squarePath?: string;
     name?: string;
     homeDir: string;
     command: string;
@@ -24,7 +23,7 @@ export declare function parseHardCap(value: string): HardCap;
 export declare function parseNameList(value: string, flag: string): string[];
 export declare function requireParticipant(name: string | undefined): string;
 export interface ParsedGlobalArgs {
-    squarePath: string;
+    squarePath?: string;
     explicitSquarePath: boolean;
     multipleSquares: boolean;
     name?: string;
@@ -32,4 +31,5 @@ export interface ParsedGlobalArgs {
 }
 export declare function parseGlobalArgs(rawArgs: string[]): ParsedGlobalArgs;
 export declare function locationIsRequired(command: string): boolean;
-export declare function defaultContext(command: string, squarePath: string, name?: string): CommandContext;
+export declare function defaultContext(command: string, squarePath?: string, name?: string): CommandContext;
+export declare function requireSquarePath(context: CommandContext): string;

package/dist/cli/context.js

@@ -3,7 +3,6 @@ import os from 'node:os';
 import { commandUsageHint } from '../help.js';
 import { parseParticipantList, validateName } from '../model.js';
 import { localParticipantName } from '../registry.js';
-export const DEFAULT_SQUARE_PATH = '.square/SQUARE.square';
 export function readStdinSync() {
     try {
         return fs.readFileSync(0, 'utf8');
@@ -87,7 +86,23 @@ export function requireParticipant(name) {
     validateName(name);
     return name;
 }
-const LOCATION_REQUIRED_COMMANDS = new Set(['join', 'catch', 'express', 'done', 'hold', 'resume']);
+const LOCATION_REQUIRED_COMMANDS = new Set([
+    'build',
+    'stream',
+    'join',
+    'catch',
+    'express',
+    'listen',
+    'ignore',
+    'listening',
+    'done',
+    'hold',
+    'resume',
+    'history',
+    'status',
+    'participants',
+    'doctor',
+]);
 function configuredLocation() {
     const value = process.env.SQUARE_LOCATION?.trim();
     return value === '' ? undefined : value;
@@ -125,9 +140,10 @@ export function parseGlobalArgs(rawArgs) {
     if (command !== undefined && !['--help', '-h'].includes(command) && locationIsRequired(command) && requestedPath === undefined && configured === undefined) {
         fail(`✕ ${command} needs a square location\n» square ls`);
     }
-    const squarePath = requestedPath ?? configured ?? DEFAULT_SQUARE_PATH;
-    if (name === undefined && command !== undefined && locationIsRequired(command))
+    const squarePath = requestedPath ?? configured;
+    if (name === undefined && squarePath !== undefined && command !== undefined && locationIsRequired(command)) {
         name = localParticipantName(squarePath);
+    }
     return { squarePath, explicitSquarePath: explicitSquarePath || configured !== undefined, multipleSquares: false, name, args };
 }
 export function locationIsRequired(command) {
@@ -136,3 +152,8 @@ export function locationIsRequired(command) {
 export function defaultContext(command, squarePath, name) {
     return { command, squarePath, name, homeDir: os.homedir() };
 }
+export function requireSquarePath(context) {
+    if (context.squarePath === undefined)
+        fail(`✕ ${context.command} needs a square location\n» square ls`);
+    return context.squarePath;
+}

package/dist/cli/harness-command.js

@@ -102,7 +102,7 @@ export function formatHarnessResult(result) {
     return `${[...result.notes, ...result.lines, ...result.failures].join('\n')}\n`;
 }
 export function runHarnessCommand(argv, squarePath) {
-    const context = { homeDir: os.homedir(), squarePath: squarePath ?? '.square/SQUARE.square', command: 'harness' };
+    const context = { homeDir: os.homedir(), ...(squarePath === undefined ? {} : { squarePath }), command: 'harness' };
     const intent = harnessCommand.parse(argv, context);
     return Promise.resolve(harnessCommand.execute(intent, context)).then(formatHarnessResult);
 }

package/dist/cli/maintenance-commands.js

@@ -1,7 +1,7 @@
 import { diagnoseSquareFile } from '../square-storage.js';
 import { renderDoctorClean, renderDoctorUnfixable, withPathOutput } from '../presentation.js';
 import { inSquareCount } from '../runtime.js';
-import { usage } from './context.js';
+import { requireSquarePath, usage } from './context.js';
 export const doctorCommand = {
     parse(argv, context) {
         if (argv.length > 0)
@@ -9,15 +9,16 @@ export const doctorCommand = {
         return undefined;
     },
     execute(_intent, context) {
-        const diagnosis = diagnoseSquareFile(context.squarePath);
+        const squarePath = requireSquarePath(context);
+        const diagnosis = diagnoseSquareFile(squarePath);
         if (diagnosis.unfixable !== undefined || diagnosis.state === undefined) {
             return {
-                output: withPathOutput(context.squarePath, renderDoctorUnfixable(diagnosis.unfixable ?? 'the snapshot could not be decoded')),
+                output: withPathOutput(squarePath, renderDoctorUnfixable(diagnosis.unfixable ?? 'the snapshot could not be decoded')),
                 exitCode: 2,
             };
         }
         return {
-            output: withPathOutput(context.squarePath, renderDoctorClean(), {
+            output: withPathOutput(squarePath, renderDoctorClean(), {
                 participantCount: inSquareCount(diagnosis.state),
             }),
         };

package/dist/cli/observation-commands.js

@@ -12,7 +12,7 @@ import { cmdWatch } from '../watch.js';
 import { openSquare } from '../square-file-adapter.js';
 import { closeOpenSquare } from '../open-square.js';
 import { historyPresentation, participantsPresentation, statusPresentation } from '../views.js';
-import { fail, parseDurationMs, parseNameList, parseNonNegativeInteger, readStdinSync, requireParticipant, requireValue, usage, } from './context.js';
+import { fail, parseDurationMs, parseNameList, parseNonNegativeInteger, readStdinSync, requireParticipant, requireSquarePath, requireValue, usage, } from './context.js';
 export const listCommand = {
     parse: (argv) => argv,
     async execute(argv, context) {
@@ -39,10 +39,11 @@ export const streamCommand = {
         return { ndjson, forName };
     },
     async execute(intent, context) {
+        const squarePath = requireSquarePath(context);
         if (intent.ndjson)
-            await cmdStreamNdjson(context.squarePath, intent.forName);
+            await cmdStreamNdjson(squarePath, intent.forName);
         else
-            await cmdStream(context.squarePath);
+            await cmdStream(squarePath);
     },
     present: () => { },
 };
@@ -93,8 +94,9 @@ export const catchCommand = {
         };
     },
     async execute(intent, context) {
-        await cmdWatch(context.squarePath, requireParticipant(context.name), intent);
-        await sweepPendingNotifications(context.squarePath);
+        const squarePath = requireSquarePath(context);
+        await cmdWatch(squarePath, requireParticipant(context.name), intent);
+        await sweepPendingNotifications(squarePath);
     },
     present: () => { },
 };
@@ -111,6 +113,7 @@ function parseTimestamp(value, flag) {
     return timestamp;
 }
 function parseHistory(argv, context) {
+    const squarePath = requireSquarePath(context);
     const viewer = context.name;
     let lastN = 10;
     let lastNExplicit = false;
@@ -133,7 +136,7 @@ function parseHistory(argv, context) {
         const flag = argv[index];
         if (flag === '--limit') {
             const value = argv[index + 1];
-            const retry = `${commandPrefix(context.squarePath)} history --limit 30`;
+            const retry = `${commandPrefix(squarePath)} history --limit 30`;
             if (value === undefined || value.startsWith('--'))
                 fail(`✕ --limit needs a positive number\n» ${retry}`);
             if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value))) {
@@ -283,6 +286,7 @@ function renderHistoryProjection(projection, visible, full, squarePath, viewer,
         const options = {
             preview,
             actNumber: activity.kind === 'say' ? projection.sayNumbers[activity.index] : undefined,
+            perception: activity.perception,
         };
         const rendered = mode === 'archive'
             ? renderEventCli(activity, options)
@@ -302,7 +306,8 @@ function renderHistoryProjection(projection, visible, full, squarePath, viewer,
 export const historyCommand = {
     parse(argv, context) { return parseHistory(argv, context); },
     async execute(options, context) {
-        const square = await openSquare(context.squarePath, { clock: nowMs });
+        const squarePath = requireSquarePath(context);
+        const square = await openSquare(squarePath, { clock: nowMs });
         try {
             const projection = await historyPresentation(square, options);
             let events = [...projection.activities];
@@ -324,9 +329,9 @@ export const historyCommand = {
                 || (options.lastN == null && options.full === true)
                 || anonymous;
             const output = pattern === undefined || pattern === ''
-                ? renderHistoryProjection(projection, events, options.full === true || anonymous, context.squarePath, options.viewer ?? '', archive ? 'archive' : 'ambient')
-                : renderGrepActivitiesView(events, totalMatches, options.full, context.squarePath, pattern, options.fixed !== undefined);
-            return withPathOutput(context.squarePath, output, { participantCount: projection.participantCount });
+                ? renderHistoryProjection(projection, events, options.full === true || anonymous, squarePath, options.viewer ?? '', archive ? 'archive' : 'ambient')
+                : renderGrepActivitiesView(events, totalMatches, options.full, squarePath, pattern, options.fixed !== undefined);
+            return withPathOutput(squarePath, output, { participantCount: projection.participantCount });
         }
         finally {
             await closeOpenSquare(square);
@@ -338,7 +343,8 @@ export const participantsCommand = {
     parse(argv, context) { if (argv.length > 0)
         usage(context.command); return undefined; },
     async execute(_intent, context) {
-        const square = await openSquare(context.squarePath, { clock: nowMs });
+        const squarePath = requireSquarePath(context);
+        const square = await openSquare(squarePath, { clock: nowMs });
         try {
             const now = nowMs();
             const participants = await participantsPresentation(square);
@@ -349,7 +355,7 @@ export const participantsCommand = {
                 return `  ${glyph} ${participantIdentity(participant.name)} · ${state} · ${participant.activityCount} ${participant.activityCount === 1 ? 'activity' : 'activities'} · ${last}`;
             });
             const participantCount = participants.filter((participant) => participant.state === 'active').length;
-            return withPathOutput(context.squarePath, ['participants', ...lines].join('\n'), {
+            return withPathOutput(squarePath, ['participants', ...lines].join('\n'), {
                 participantCount,
             });
         }
@@ -363,7 +369,8 @@ export const statusCommand = {
     parse(argv, context) { if (argv.length > 0)
         usage(context.command); return undefined; },
     async execute(_intent, context) {
-        const square = await openSquare(context.squarePath, { clock: nowMs });
+        const squarePath = requireSquarePath(context);
+        const square = await openSquare(squarePath, { clock: nowMs });
         try {
             const presentation = await statusPresentation(square);
             const result = presentation.status;
@@ -387,7 +394,7 @@ export const statusCommand = {
                 const attention = !showAttention
                     ? ''
                     : participant.pendingMentionCount > 0
-                        ? `${participant.pendingMentionCount} mention${participant.pendingMentionCount === 1 ? '' : 's'} waiting`
+                        ? `${participant.pendingMentionCount} attention${participant.pendingMentionCount === 1 ? '' : 's'} waiting`
                         : participant.unreadActivityCount > 0
                             ? `${participant.unreadActivityCount} change${participant.unreadActivityCount === 1 ? '' : 's'} waiting`
                             : 'caught up';
@@ -405,6 +412,7 @@ export const statusCommand = {
                     now: result.now,
                     preview: 200,
                     actNumber: presentation.latestActNumber,
+                    squareState: presentation.state,
                 });
             const latest = visible === ''
                 ? [result.latestAct === undefined
@@ -412,14 +420,14 @@ export const statusCommand = {
                         : '  · latest activity is private to another participant']
                 : [`  ${visible.replace(/\n/g, '\n  ')}`];
             if (visible.includes('more chars') && result.latestAct !== undefined) {
-                const prefix = context.name === undefined ? commandPrefix(context.squarePath) : participantCommandPrefix(context.squarePath, context.name);
+                const prefix = context.name === undefined ? commandPrefix(squarePath) : participantCommandPrefix(squarePath, context.name);
                 latest.push(`» ${prefix} history --at ${actId(result.latestAct)} -C 2 --full`);
             }
             const output = [
                 `${result.activeCount} active · ${result.doneCount} done · cap ${cap} · throttle ${result.throttlePerMinute === undefined ? 'none' : `${result.throttlePerMinute}/min`}`,
                 ...(hold === undefined ? [] : ['', hold]), '', 'around the square', ...people, '', 'latest', ...latest,
             ].join('\n');
-            return withPathOutput(context.squarePath, output, { participantCount: result.activeCount, held: result.holdActive });
+            return withPathOutput(squarePath, output, { participantCount: result.activeCount, held: result.holdActive });
         }
         finally {
             await closeOpenSquare(square);

package/dist/cli/program.js

@@ -14,7 +14,7 @@ export async function runCli(rawArgs = process.argv.slice(2)) {
     try {
         const requestedHelp = helpRequest(rawArgs);
         if (requestedHelp !== undefined) {
-            await executeRegisteredCommand('help', requestedHelp.command === undefined ? [] : [requestedHelp.command], defaultContext('help', '.square/SQUARE.square'));
+            await executeRegisteredCommand('help', requestedHelp.command === undefined ? [] : [requestedHelp.command], defaultContext('help'));
             return;
         }
         const parsed = parseGlobalArgs(rawArgs);

package/dist/cli/registry.js

@@ -1,4 +1,4 @@
-import { buildCommand, doneCommand, expressCommand, holdCommand, joinCommand, resumeCommand } from './square-commands.js';
+import { buildCommand, doneCommand, expressCommand, holdCommand, ignoreCommand, joinCommand, listenCommand, listeningCommand, resumeCommand } from './square-commands.js';
 import { doctorCommand } from './maintenance-commands.js';
 import { harnessCommand, installCommand, uninstallCommand } from './harness-command.js';
 import { helpCommand, versionCommand } from './meta-commands.js';
@@ -14,6 +14,9 @@ export const commandRegistry = [
     { names: ['codex-hook'], spec: codexHookCommand },
     { names: ['catch'], spec: catchCommand },
     { names: ['express'], spec: expressCommand },
+    { names: ['listen'], spec: listenCommand },
+    { names: ['ignore'], spec: ignoreCommand },
+    { names: ['listening'], spec: listeningCommand },
     { names: ['done'], spec: doneCommand },
     { names: ['hold'], spec: holdCommand },
     { names: ['resume'], spec: resumeCommand },

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

@@ -23,9 +23,16 @@ interface BodyIntent {
     name: string;
     body?: string;
 }
+interface ListenerIntent {
+    name: string;
+    target?: string;
+}
 export declare const buildCommand: CommandSpec<BuildIntent, string>;
 export declare const joinCommand: CommandSpec<JoinIntent, string>;
 export declare const expressCommand: CommandSpec<ActivityIntent>;
+export declare const listenCommand: CommandSpec<ListenerIntent, string>;
+export declare const ignoreCommand: CommandSpec<ListenerIntent, string>;
+export declare const listeningCommand: CommandSpec<ListenerIntent, string>;
 export declare const doneCommand: CommandSpec<BodyIntent, string>;
 export declare const holdCommand: CommandSpec<BodyIntent, string>;
 export declare const resumeCommand: CommandSpec<{