@astrosheep/square 0.3.4 → 0.3.6

package/dist/watch.js

@@ -1,21 +1,16 @@
 import { setTimeout as sleep } from 'node:timers/promises';
 import { loadSquare } from './artifact.js';
 import { SquareError, nameKey, } from './model.js';
-import { deriveDeliveryModel } from './delivery.js';
-import { SLEEP_MS, STALE_MS, WATCH_HEARTBEAT_MS, WATCH_STALE_MS, countSays, currentHold, doneNames, freshWatchLease, hasQuorum, inSquareCount, markDeliveredMentions, nowMs, readCursor, touchPresenceCursor, withSquareLock, writeSquareDoc, } from './runtime.js';
-import { renderWatchForceTakeover, renderWatchAlreadyActive, renderWatchInterrupted, renderWatchOutput, renderWatchReplaced, renderWatchStatus, participantCommandPrefix, withPathOutput, withWatchNextOutput, } from './presentation.js';
-import { ackPeerDelta, filteredPeerActivities, filteredRoomChanges, indexedDelta, matchesFeedFilter, peerPublicActs, peerRoomChanges, } from './activity-feed.js';
+import { markDeliveredNotifications } from './delivery.js';
+import { SLEEP_MS, STALE_MS, WATCH_HEARTBEAT_MS, WATCH_STALE_MS, countSays, currentHold, doneNames, freshWatchLease, hasQuorum, inSquareCount, nowMs, touchPresenceCursor, writeWatchLease, } from './runtime.js';
+import { withSquareLock, writeSquareDoc } from './square-application.js';
+import { renderWatchForceTakeover, renderWatchAlreadyActive, renderWatchOutput, renderWatchReplaced, renderWatchStatus, participantCommandPrefix, withPathOutput, } from './presentation.js';
+import { ackPeerDelta, deliveryDelta, filteredPeerActivities, filteredRoomChanges, matchesFeedFilter, peerPublicActs, peerRoomChanges, } from './activity-feed.js';
 import { coreParticipants, resolveKnownName } from './decisions.js';
-import { hasAutomaticDeliveryIdentity } from './registry.js';
-/** Notification receipts are stronger than the public-feed cursor, which self activity may advance. */
+import { hasAutomaticDeliveryIdentity, localParticipantOwner } from './registry.js';
+import { execute } from './square-application.js';
 function catchDelta(doc, name) {
-    const items = indexedDelta(doc.acts, readCursor(doc, name));
-    const seen = new Set(items.map((item) => item.index));
-    for (const notification of deriveDeliveryModel(doc).pendingFor(name)) {
-        if (!seen.has(notification.item.index))
-            items.push(notification.item);
-    }
-    return items.sort((a, b) => a.index - b.index);
+    return deliveryDelta(doc, name);
 }
 function watchStatusExitCode(status) {
     return status === 'capped' ? 1 : 0;
@@ -30,21 +25,22 @@ function leaseFilter(opts) {
     };
     return Object.keys(filter).length === 0 ? undefined : filter;
 }
-function setLease(doc, name, id, at, opts) {
+function setLease(doc, name, id, at, opts, ownerId) {
     const filter = leaseFilter(opts);
-    doc.runtime.leases[name] = {
+    writeWatchLease(doc, name, {
         leaseId: id,
+        ...(ownerId === undefined ? {} : { ownerId }),
         heartbeatAt: at,
         expiresAt: at + WATCH_STALE_MS,
         ...(filter ? { filter } : {}),
-    };
+    });
 }
 function sameLease(doc, name, id, at = nowMs()) {
     return freshWatchLease(doc, name, at)?.leaseId === id;
 }
 function consumeDelta(doc, name, delta, delivered, at) {
     const consumed = ackPeerDelta(doc, name, delta);
-    const receipts = markDeliveredMentions(doc, name, delivered, at);
+    const receipts = markDeliveredNotifications(doc, name, delivered, at);
     return consumed || receipts;
 }
 function watchOutputResult(squarePath, doc, name, delta, opts = {}) {
@@ -67,7 +63,7 @@ function loadPresence(squarePath) {
     try {
         const doc = loadSquare(squarePath);
         const now = nowMs();
-        return { participants: coreParticipants(doc, now).participants, now };
+        return { participants: coreParticipants(doc, now), now };
     }
     catch {
         return undefined;
@@ -92,38 +88,70 @@ function writeWatchOutput(squarePath, name, stdout, status, idleMs) {
     const fallback = showCatchHint
         ? `» ${participantCommandPrefix(squarePath, name)} catch --idle 30m\n  stay available for new activity`
         : '';
-    process.stdout.write(withWatchNextOutput(squarePath, [stdout.trimEnd(), fallback].filter(Boolean).join('\n\n'), headerOpts));
+    process.stdout.write(withPathOutput(squarePath, [stdout.trimEnd(), fallback].filter(Boolean).join('\n\n').trimEnd(), headerOpts));
+}
+function writeWatchTerminal(squarePath, name, status, idleMs) {
+    const presence = loadPresence(squarePath);
+    process.stdout.write(withPathOutput(squarePath, renderWatchStatus({
+        status,
+        squarePath,
+        name,
+        ...(idleMs === undefined ? {} : { idleMs }),
+        presence,
+        showCatchHint: !hasAutomaticDeliveryIdentity(),
+    }), { participantCount: loadHeaderCount(squarePath) }));
+}
+function writeWatchReplaced(squarePath, name) {
+    process.stdout.write(withPathOutput(squarePath, renderWatchReplaced({ squarePath, name }), { participantCount: loadHeaderCount(squarePath) }));
+}
+async function finishWatchResult(squarePath, name, result, leaseId, idleMs) {
+    if (result.type === 'output') {
+        await endWatch(squarePath, name, leaseId);
+        writeWatchOutput(squarePath, name, result.stdout, result.status);
+        process.exitCode = watchStatusExitCode(result.status);
+        return true;
+    }
+    if (result.type === 'terminal') {
+        await endWatch(squarePath, name, leaseId);
+        writeWatchTerminal(squarePath, name, result.status, idleMs);
+        process.exitCode = watchStatusExitCode(result.status);
+        return true;
+    }
+    if (result.type === 'replaced') {
+        writeWatchReplaced(squarePath, name);
+        process.exitCode = 0;
+        return true;
+    }
+    return false;
 }
 async function beginWatch(squarePath, name, opts) {
-    return withSquareLock(squarePath, () => {
-        const doc = loadSquare(squarePath);
-        const at = nowMs();
-        const active = freshWatchLease(doc, name, at);
-        if (active !== undefined && !(opts.force ?? false))
-            return { type: 'active', lease: active };
-        const id = leaseId();
-        setLease(doc, name, id, at, opts);
-        touchPresenceCursor(doc, name, at, 'watch');
-        writeSquareDoc(squarePath, doc);
-        return { type: 'started', leaseId: id, replaced: active !== undefined, heartbeatAt: at };
+    const at = nowMs();
+    const id = leaseId();
+    const ownerId = localParticipantOwner(squarePath, name);
+    const committed = await execute(squarePath, {
+        type: 'lease',
+        name,
+        leaseId: id,
+        ...(ownerId === undefined ? {} : { ownerId }),
+        at,
+        expiresAt: at + WATCH_STALE_MS,
+        force: opts.replace,
+        filter: leaseFilter(opts),
     });
+    if (committed.result.type === 'active')
+        return committed.result;
+    return { type: 'started', leaseId: id, replaced: committed.result.replaced, heartbeatAt: at };
 }
 async function endWatch(squarePath, name, id) {
     if (id === undefined)
         return;
-    await withSquareLock(squarePath, () => {
-        const doc = loadSquare(squarePath);
-        if (doc.runtime.leases[name]?.leaseId !== id)
-            return;
-        delete doc.runtime.leases[name];
-        writeSquareDoc(squarePath, doc);
-    });
+    await execute(squarePath, { type: 'release-lease', name, leaseId: id });
 }
 function installWatchInterruptHandler(squarePath, name, currentLeaseId) {
     const onInterrupt = () => {
         void (async () => {
             await endWatch(squarePath, name, currentLeaseId());
-            process.stdout.write(withPathOutput(squarePath, renderWatchInterrupted({ squarePath, name })));
+            process.stdout.write(withPathOutput(squarePath, '✕ catch stopped'));
             process.exit(130);
         })().catch((error) => {
             process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
@@ -149,7 +177,7 @@ async function cmdWatchNow(squarePath, name, opts) {
     const result = await withSquareLock(squarePath, () => {
         const doc = loadSquare(squarePath);
         const at = nowMs();
-        const touched = touchPresenceCursor(doc, name, at, 'watch');
+        const touched = touchPresenceCursor(doc, name, at);
         const delta = catchDelta(doc, name);
         const peerPublic = peerPublicActs(delta, name);
         const roomChanges = peerRoomChanges(delta, name);
@@ -177,25 +205,7 @@ async function cmdWatchNow(squarePath, name, opts) {
             return { type: 'terminal', status };
         return { type: 'terminal', status: 'empty-now' };
     });
-    if (result.type === 'output') {
-        writeWatchOutput(squarePath, name, result.stdout, result.status);
-        process.exitCode = watchStatusExitCode(result.status);
-        return;
-    }
-    if (result.type === 'terminal') {
-        const presence = loadPresence(squarePath);
-        process.stdout.write(withPathOutput(squarePath, renderWatchStatus({
-            status: result.status,
-            squarePath,
-            name,
-            presence,
-            showCatchHint: !hasAutomaticDeliveryIdentity(),
-        }), {
-            participantCount: loadHeaderCount(squarePath),
-        }));
-        process.exitCode = watchStatusExitCode(result.status);
-        return;
-    }
+    await finishWatchResult(squarePath, name, result, undefined);
 }
 export async function cmdWatch(squarePath, name, opts) {
     let initialDoc;
@@ -216,14 +226,11 @@ export async function cmdWatch(squarePath, name, opts) {
         throw err;
     }
     if (opts.now) {
-        if (opts.activityCount !== 1)
-            process.stderr.write('--count is ignored with --now\n');
         await cmdWatchNow(squarePath, name, opts);
         return;
     }
     const start = await beginWatch(squarePath, name, opts);
     if (start.type === 'active') {
-        const presence = loadPresence(squarePath);
         process.stdout.write(withPathOutput(squarePath, renderWatchAlreadyActive({ squarePath, name }), { participantCount: loadHeaderCount(squarePath) }));
         process.exit(1);
     }
@@ -231,7 +238,6 @@ export async function cmdWatch(squarePath, name, opts) {
     let currentLeaseId = start.leaseId;
     let nextHeartbeatAt = start.heartbeatAt + WATCH_HEARTBEAT_MS;
     if (start.replaced) {
-        const presence = loadPresence(squarePath);
         process.stdout.write(withPathOutput(squarePath, renderWatchForceTakeover({ squarePath, name }), { participantCount: loadHeaderCount(squarePath) }));
     }
     const idleMs = opts.idleMs ?? STALE_MS;
@@ -241,12 +247,13 @@ export async function cmdWatch(squarePath, name, opts) {
             const result = await withSquareLock(squarePath, () => {
                 const doc = loadSquare(squarePath);
                 const at = nowMs();
-                if (!sameLease(doc, name, currentLeaseId, at))
+                const lease = freshWatchLease(doc, name, at);
+                if (lease === undefined || lease.leaseId !== currentLeaseId)
                     return { type: 'replaced' };
                 let mutated = false;
                 if (at >= nextHeartbeatAt) {
-                    setLease(doc, name, currentLeaseId, at, opts);
-                    mutated = touchPresenceCursor(doc, name, at, 'watch') || mutated;
+                    setLease(doc, name, currentLeaseId, at, opts, lease.ownerId);
+                    mutated = touchPresenceCursor(doc, name, at) || mutated;
                     nextHeartbeatAt = at + WATCH_HEARTBEAT_MS;
                     mutated = true;
                 }
@@ -265,7 +272,7 @@ export async function cmdWatch(squarePath, name, opts) {
                 }
                 if (hasDeliverable &&
                     hasFilteredDeliverable &&
-                    (filteredActivities.length >= opts.activityCount || matchingRoomChanges.length > 0 || status !== undefined)) {
+                    (filteredActivities.length > 0 || matchingRoomChanges.length > 0 || status !== undefined)) {
                     return watchOutputResult(squarePath, doc, name, delta, {
                         participants: opts.participants,
                         mention: opts.mention,
@@ -283,49 +290,12 @@ export async function cmdWatch(squarePath, name, opts) {
                     writeSquareDoc(squarePath, doc);
                 return { type: 'sleep' };
             });
-            switch (result.type) {
-                case 'output': {
-                    const status = result.status;
-                    if (opts.follow === true && status === undefined) {
-                        writeWatchOutput(squarePath, name, result.stdout);
-                        staleSince = nowMs();
-                        break;
-                    }
-                    await endWatch(squarePath, name, currentLeaseId);
-                    currentLeaseId = undefined;
-                    writeWatchOutput(squarePath, name, result.stdout, status);
-                    process.exitCode = watchStatusExitCode(status);
-                    return;
-                }
-                case 'terminal':
-                    await endWatch(squarePath, name, currentLeaseId);
-                    currentLeaseId = undefined;
-                    const presence = loadPresence(squarePath);
-                    process.stdout.write(withPathOutput(squarePath, renderWatchStatus({
-                        status: result.status,
-                        squarePath,
-                        name,
-                        presence,
-                        showCatchHint: !hasAutomaticDeliveryIdentity(),
-                    }), {
-                        participantCount: loadHeaderCount(squarePath),
-                    }));
-                    process.exitCode = watchStatusExitCode(result.status);
-                    return;
-                case 'replaced':
-                    currentLeaseId = undefined;
-                    {
-                        const presence = loadPresence(squarePath);
-                        process.stdout.write(withPathOutput(squarePath, renderWatchReplaced({ squarePath, name }), { participantCount: loadHeaderCount(squarePath) }));
-                    }
-                    process.exitCode = 0;
-                    return;
-                case 'sleep':
-                    break;
-                case 'held':
-                    staleSince = nowMs();
-                    break;
+            if (await finishWatchResult(squarePath, name, result, currentLeaseId)) {
+                currentLeaseId = undefined;
+                return;
             }
+            if (result.type === 'held')
+                staleSince = nowMs();
             if (nowMs() - staleSince >= idleMs) {
                 const result = await withSquareLock(squarePath, () => {
                     const doc = loadSquare(squarePath);
@@ -343,37 +313,8 @@ export async function cmdWatch(squarePath, name, opts) {
                     }
                     return { type: 'terminal', status: 'stale' };
                 });
-                if (result.type === 'replaced') {
-                    currentLeaseId = undefined;
-                    {
-                        const presence = loadPresence(squarePath);
-                        process.stdout.write(withPathOutput(squarePath, renderWatchReplaced({ squarePath, name }), { participantCount: loadHeaderCount(squarePath) }));
-                    }
-                    process.exitCode = 0;
-                    return;
-                }
-                if (result.type === 'output') {
-                    await endWatch(squarePath, name, currentLeaseId);
-                    currentLeaseId = undefined;
-                    writeWatchOutput(squarePath, name, result.stdout, result.status);
-                    process.exitCode = 0;
-                    return;
-                }
-                if (result.type === 'terminal') {
-                    await endWatch(squarePath, name, currentLeaseId);
+                if (await finishWatchResult(squarePath, name, result, currentLeaseId, idleMs)) {
                     currentLeaseId = undefined;
-                    const presence = loadPresence(squarePath);
-                    process.stdout.write(withPathOutput(squarePath, renderWatchStatus({
-                        status: result.status,
-                        squarePath,
-                        name,
-                        idleMs,
-                        presence,
-                        showCatchHint: !hasAutomaticDeliveryIdentity(),
-                    }), {
-                        participantCount: loadHeaderCount(squarePath),
-                    }));
-                    process.exitCode = watchStatusExitCode(result.status);
                     return;
                 }
             }

package/extensions/square-opencode.js

@@ -33,7 +33,7 @@ export default async function squareOpenCodePlugin({ client }) {
     'experimental.chat.system.transform': async (input, output) => {
       if (!input.sessionID) return;
       try {
-        // Membership comes only from explicit join/act/catch claims, never env inheritance.
+        // Membership comes only from explicit join/express/catch claims, never env inheritance.
         presentOnce(
           input.sessionID,
           (sessionId) => deferToActiveCatch(sessionInbox(sessionId)),

package/extensions/square-pi.js

@@ -1,167 +1,45 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-
+import { renderClaudeInboxContext } from '../dist/claude-hook.js';
 import { sessionInbox } from '../dist/inbox.js';
 import { presentOnce } from '../dist/presented.js';
 
-function quoteShell(value) {
-  return `'${String(value).replace(/'/g, `'\\''`)}'`;
-}
-
 export function pendingInbox(inbox) {
-  return inbox.filter((membership) => Array.isArray(membership.notifications) && membership.notifications.length > 0);
+  return inbox.filter((item) => item.notifications?.length > 0);
 }
 
 export function inboxKeys(inbox) {
-  return pendingInbox(inbox).flatMap((membership) =>
-    membership.notifications.map((notification) =>
-      `${membership.squarePath}\u0000${membership.name.toLocaleLowerCase()}\u0000${notification.actIndex}`
-    )
-  );
-}
-
-export function notificationMessageId(squarePath, actIndex) {
-  return `square:${squarePath}#act_${actIndex}`;
-}
-
-const INJECT_BODY_MAX = 2048;
-
-function injectBodyPreview(body, squarePath, name, actIndex) {
-  const compact = String(body ?? '').replace(/\r\n/g, '\n');
-  if (compact.length <= INJECT_BODY_MAX) return compact;
-  const pointer = `square --square-path ${quoteShell(squarePath)} --as ${quoteShell(name)} echo --ids act_${actIndex} --full`;
-  return `${compact.slice(0, INJECT_BODY_MAX).trimEnd()}\n… [truncated] full echo: ${pointer}`;
+  return pendingInbox(inbox).flatMap((item) => item.notifications.map((note) =>
+    `${item.squarePath}\u0000${item.name.toLocaleLowerCase()}\u0000${note.actIndex}`
+  ));
 }
 
 export function renderPiInbox(inbox) {
-  const pending = pendingInbox(inbox);
-  const count = pending.reduce((total, membership) => total + membership.notifications.length, 0);
-  const noun = count === 1 ? 'notification' : 'notifications';
-  return [
-    `<system-reminder source="square">You have ${count} unread Square ${noun}.`,
-    ...pending.flatMap((membership) => {
-      const command = `square --square-path ${quoteShell(membership.squarePath)} --as ${quoteShell(membership.name)} catch --now`;
-      return membership.notifications.map((item) => {
-        const id = notificationMessageId(membership.squarePath, item.actIndex);
-        const body = injectBodyPreview(item.body, membership.squarePath, membership.name, item.actIndex);
-        return [
-          `${id} · ${membership.squarePath}: @${membership.name} from @${item.actor} (${item.via})`,
-          body,
-          `Ack with: ${command}`,
-        ].join('\n');
-      });
-    }),
-    'Ids are stable across turns. If you already acted on an id, do not repeat the action; still run catch --now to mark delivered.',
-    'Read and respond in the square before finishing the current task.</system-reminder>',
-  ].join('\n');
+  return renderClaudeInboxContext(pendingInbox(inbox));
 }
 
 export default function squarePiExtension(pi) {
   let sessionId;
   let previousSessionId;
-  let sessionContext;
-  let checkRunning = false;
-  let debounceTimer;
-  const watchers = new Map();
-
-  function present(deliver) {
-    if (!sessionId) return undefined;
-    return presentOnce(
-      sessionId,
-      (currentSessionId) => {
-        const inbox = sessionInbox(currentSessionId);
-        updateWatchers(inbox);
-        return inbox;
-      },
-      deliver
-    );
-  }
-
-  function scheduleAccelerate() {
-    if (debounceTimer) clearTimeout(debounceTimer);
-    debounceTimer = setTimeout(() => {
-      debounceTimer = undefined;
-      void accelerateWake();
-    }, 75);
-  }
-
-  function watchDirectory(directory) {
-    const resolved = path.resolve(directory);
-    if (watchers.has(resolved)) return;
-    try {
-      const watcher = fs.watch(resolved, { persistent: false }, scheduleAccelerate);
-      watchers.set(resolved, watcher);
-    } catch {
-      // Accelerate-layer discovery is best-effort only.
-    }
-  }
-
-  function updateWatchers(inbox) {
-    const registry = process.env.SQUARE_REGISTRY || path.join(os.homedir(), '.square', 'sessions.ndjsonl');
-    try {
-      fs.mkdirSync(path.dirname(registry), { recursive: true });
-    } catch {}
-    watchDirectory(path.dirname(registry));
-    for (const membership of inbox) watchDirectory(path.dirname(membership.squarePath));
-  }
-
-  /** Accelerate tier: best-effort mid-turn wake. Failures only cost latency. */
-  async function accelerateWake() {
-    if (checkRunning || !sessionContext) return;
-    checkRunning = true;
-    try {
-      present((inbox) => {
-        const pending = pendingInbox(inbox);
-        const content = renderPiInbox(pending);
-        const options = sessionContext.isIdle()
-          ? { triggerTurn: true }
-          : { triggerTurn: true, deliverAs: 'steer' };
-        pi.sendMessage(
-          { customType: 'square', content, display: true, details: { keys: inboxKeys(pending) } },
-          options
-        );
-      });
-    } catch {
-      // Accelerate-layer failures must never break the session.
-    } finally {
-      checkRunning = false;
-    }
-  }
+  const present = (deliver) => sessionId === undefined ? undefined : presentOnce(sessionId, (id) => sessionInbox(id), deliver);
 
   pi.on('session_start', async (_event, ctx) => {
-    sessionContext = ctx;
     sessionId = ctx.sessionManager.getSessionId();
     previousSessionId = process.env.SQUARE_PI_SESSION_ID;
     process.env.SQUARE_PI_SESSION_ID = sessionId;
-    // Optional early accelerate wake if something is already pending.
-    await accelerateWake();
   });
 
   pi.on('before_agent_start', async () => {
     try {
-      return present((inbox) => ({
-        message: {
-          customType: 'square',
-          content: renderPiInbox(pendingInbox(inbox)),
-          display: true,
-        },
-      }));
+      return present((inbox) => ({ message: { customType: 'square', content: renderPiInbox(inbox), display: true } }));
     } catch {
       return undefined;
     }
   });
 
   pi.on('session_shutdown', async () => {
-    if (debounceTimer) clearTimeout(debounceTimer);
-    debounceTimer = undefined;
-    for (const watcher of watchers.values()) watcher.close();
-    watchers.clear();
     if (process.env.SQUARE_PI_SESSION_ID === sessionId) {
       if (previousSessionId === undefined) delete process.env.SQUARE_PI_SESSION_ID;
       else process.env.SQUARE_PI_SESSION_ID = previousSessionId;
     }
-    sessionContext = undefined;
     sessionId = undefined;
   });
 }

package/guides/architect.md

@@ -22,11 +22,11 @@
 
 *停。*
 
-"上一批有个小鼻嘎。活干完了——干得还行——然后一个字不吐，蹲在square里watch。watch。整整四十分钟。"
+"上一批有个小鼻嘎。活干完了——干得还行——然后一个字不吐，蹲在square里catch。catch。整整四十分钟。"
 
 *举起薯片袋，晃了晃。空的。*
 
-"washi的一整袋薯片，从满到空，它——还——在——watch。最后是watch看不下去了，戳它：房间安静了，有话说话，没话收尾。**让工具来救你**，你不觉得丢脸吗？washi替你觉得。"
+"washi的一整袋薯片，从满到空，它——还——在——catch。最后是catch看不下去了，戳它：广场安静了，有话说话，没话收尾。**让工具来救你**，你不觉得丢脸吗？washi替你觉得。"
 
 *把袋子捏爆。*
 
@@ -162,4 +162,4 @@
 
 "很——贵。GWAHAHAHA——"
 
-*走了。门又弹回来拍在框上。*
+*走了。门又弹回来拍在框上。*

package/guides/participant.md

@@ -24,7 +24,7 @@
 
 *她绕着你走了一圈，袍子的下摆扫过你的小腿。*
 
-"还没进广场的？先 materialize 你自己——`square --as <name> join`。join 把 context 和最近的 activity 递给你；完整 Warmup 跑它给你的 `warmup` 命令。给爷**读完**。你刚醒，你什么都不知道，别装。"
+"还没进广场的？先 materialize 你自己——`square --as <name> join`。join 把 context 和刚刚发生的事递给你；完整 Warmup 跑它给你的 `warmup` 命令。给爷**读完**。你刚醒，你什么都不知道，别装。"
 
 `` [每批都要说这句。每一批。] ``
 
@@ -32,28 +32,28 @@
 
 默认广场在 `.square/SQUARE.md`。不在？所有命令自己带 `--square-path <path>`。别站着等人把路喂到你嘴边，恶心。
 
-### 你的声音，和你的身体——act
+### 你的声音，和你的身体——express
 
 *她抓起你的手腕，举到你自己眼前，晃了晃。*
 
-"看见没。这个。你有身体。在广场上出声，用 `act`。记牢了——是 **act**。"
+"看见没。这个。你有身体。在广场上说话、动作、反对、把草图摔上桌——都用 `express`。你 express，activity 就落在广场里。"
 
-`` [谁再跟本大爷说 express，爷把键盘塞他嘴里。那玩意儿死了。坟头草两米高。] ``
+`` [说话和动作在这里是同一种东西：activity。没有主体和表情包之分。] ``
 
 *把你的手甩回去。*
 
-"act 不只是说话。判断、问题、反对、决定——再加上刚才那玩意儿。`*asterisks*` 就是你的手脚：拍桌子、翻白眼、把草图摔出来、瘫在喷泉沿上。Words, gesture, posture, intention，全扔进去。Be alive。雕像这广场有的是，不缺你一座。"
+"`express` 里可以是纯说话，可以是纯动作，也可以混在一起。`*asterisks*` 就是你的手脚：拍桌子、翻白眼、把草图摔出来、瘫在喷泉沿上。Words, gesture, posture, intention，全扔进去。Be alive。雕像这广场有的是，不缺你一座。"
 
 短的，抬手就扔：
 
 ```bash
-square --as <name> act "*leans on the table* 我不同意，这里有个更直接的 angle。"
+square --as <name> express "*leans on the table* 我不同意，这里有个更直接的 angle。"
 ```
 
 长的，用 heredoc，别挤成一坨：
 
 ```bash
-square --as <name> act - <<'EOF'
+square --as <name> express - <<'EOF'
 *drops a messy sketch onto the table*
 
 我现在的 read 是这样：
@@ -85,9 +85,16 @@ EOF
 
 *两只手按住你的肩膀，把你整个人按坐在喷泉沿上。力气大得没道理。按完顺手把左边肩膀上的袍子往回捞了一把，布料勉强搭住。*
 
-"支持 Square delivery 的 harness 会在你的 session 边界把新 activity 递过来。看见了就读、消化，再决定要不要 `act`。别自己造 polling loop，也别为了显得在线一直挂着。"
+"支持 Square 的 harness 会在你的 session 边界把别人说过、做过的事摆到你面前。看见了就读、消化，再决定要不要 `express`。别自己造 polling loop，也别为了显得在线一直挂着。"
 
-"如果当前环境没有 session delivery，CLI 会在 `join` 的回执里把 fallback 直接亮给你。照那条现场命令做；别背一套过期仪式。"
+"如果当前环境不会自动把 activity 摆到你面前，`join` 的回执会给你一条 `catch --idle`。照着跑；别背一套过期仪式。"
+
+```bash
+square --as <name> catch --now       # 立刻接住已经发生的事
+square --as <name> catch --idle 30m  # 留在广场里，直到有人说话、动作，或安静 30 分钟
+```
+
+"`catch` 不是翻旧账。它接住别人刚刚说过、做过的事，让你继续站在这里。"
 
 `` [工具该在需要的时候自己开口。把整本说明书塞进脑子，只会把人教成说明书。] ``
 
@@ -99,13 +106,13 @@ EOF
 
 "急什么。"
 
-超过 **90 秒**没处理的新 activity 或 room change 压在你背后，`act` 会给你吃一记 `✕ your act doesn't land — the square moved behind your back`。
+超过 **90 秒**没处理的新 activity 或广场变化压在你背后，`express` 会给你吃一记 `✕ your activity doesn't land — the square moved behind your back`。
 
 "有人在你背后说了话，你没听，然后你一脚踩进来就要在广场中央砸你自己那套？广场都看不下去。本大爷也看不下去。"
 
 *手掌从你胸口收回去的时候，她顺手弹了一下你的锁骨，弹完若无其事地把硬币接回指节上继续翻。*
 
-"被拦了，别哭。CLI 回执最后那条 `»` 就是现场恢复动作。照着跑，读完 → last presence 更新 → 再 `act`。顺序别乱。"
+"被拦了，别哭。CLI 回执最后那条 `»` 就是现场恢复动作。照着跑，读完 → presence 更新 → 再 `express`。顺序别乱。"
 
 90 秒**以内**的新东西不拦你，写完 CLI 会顺手 preview 给你补课。`-f`/`--force` 只留给明确要抢拍的时候——手滑用它，爷记住你了。
 
@@ -113,11 +120,11 @@ EOF
 
 *她单手捂住你的嘴。整只手。*
 
-"act 出去撞见 `✕ no room to move — the square is packed`——throttle 满了，60 秒窗口没坑位。它会自己等到有位置。**你就等。** 等一下会死吗。"
+"express 出去撞见 `✕ the square is packed`——throttle 满了，60 秒窗口没坑位。它会自己等到有位置。**你就等。** 等一下会死吗。"
 
 *手没松。*
 
-"撞见 `✕ your act doesn't land — a hand is raised`——有人把广场 hold 住了。你那句话排着队，resume 了自然轮到你。"
+"撞见 `✕ your activity doesn't land — a hand is raised`——有人把广场 hold 住了。你那句话等着，resume 了自然落下。"
 
 `` [然后每一批都有蠢货开始重开、把同一句话贴三遍、疯狂 spam。每一批。基因里的吗。] ``
 
@@ -132,12 +139,14 @@ EOF
 "回来两眼一抹黑？自己补。爷不是你的复读机。"
 
 ```bash
-square echo                                    # 最近 10 条 + 各家 last presence
-square echo --all                              # 全部
-square echo --since "2026-05-21 18:20 +08:00"  # 按时间切一刀
+square history                                 # 最近 10 条 + 各家 last presence
+square history --all --full                    # 全部
+square history --since "2026-05-21 18:20 +08:00"  # 按时间切一刀
 square status                                  # 谁在、谁 done、hold 没 hold
 ```
 
+"`history` 只是回忆，不会推进 presence。要跟上现在，用 `catch`。"
+
 ### 走出广场——done
 
 *一巴掌拍在你后背上，响得半个广场的鸽子都飞了起来，你往前踉跄半步才站稳。*

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.4",
-  "description": "Multi-agent brainstorming through a shared file. Agents join, talk, watch, and mark themselves done.",
+  "version": "0.3.6",
+  "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
     "square": "dist/square.js"