@astrosheep/square 0.3.61 → 0.3.62

package/extensions/square-pi.js

@@ -1,8 +1,7 @@
 import { presentPendingAtBoundary, renderPendingAtBoundary } from '../dist/boundary-presentation.js';
 import { automaticSessionEnd, automaticSessionStart } from '../dist/automatic-session.js';
-import { sessionInbox, waitForSessionPending } from '../dist/inbox.js';
-import { projectSessionBindings } from '../dist/square-projections.js';
-import { createHostLedgerPort } from '../dist/host-ledger-file-adapter.js';
+import { sessionInbox, observeSessionPending } from '../dist/inbox.js';
+import { renderAttentionDescription } from '../dist/attention-presentation.js';
 
 class PiDeliveryDroppedError extends Error {
   constructor() {
@@ -11,10 +10,6 @@ class PiDeliveryDroppedError extends Error {
   }
 }
 
-function sessionBindings(sessionId) {
-  return projectSessionBindings({ hostLedger: createHostLedgerPort(), sessionId });
-}
-
 export function pendingInbox(inbox) {
   return inbox.filter((item) => item.notifications?.length > 0);
 }
@@ -37,14 +32,10 @@ function framePiMessage(content) {
 
 export function summarizePendingForNotify(pending) {
   const lines = pending.flatMap((membership) => membership.notifications.map((note) => {
-    const verb = note.route === 'bell'
-      ? 'rang the bell'
-      : note.route === 'mention'
-        ? `called your name (${membership.name})`
-        : `spoke within your earshot (${membership.name})`;
+    const description = renderAttentionDescription({ actor: note.actor, recipient: membership.name, route: note.route });
     const body = note.body.replace(/\s+/g, ' ').trim();
     const clipped = body.length > NOTIFY_BODY_MAX ? `${body.slice(0, NOTIFY_BODY_MAX).trimEnd()}…` : body;
-    return `${note.actor} ${verb}${clipped ? ` — ${clipped}` : ''}`;
+    return `${description}${clipped ? ` — ${clipped}` : ''}`;
   }));
   if (lines.length === 0) return undefined;
   return lines.length === 1 ? `■ square · ${lines[0]}` : `■ square · ${lines[0]} (+${lines.length - 1} more)`;
@@ -133,6 +124,7 @@ export default function squarePiExtension(pi) {
   };
 
   const pause = (signal, delayMs) => new Promise((resolve) => {
+    if (signal.aborted) { resolve(); return; }
     const finish = () => {
       signal.removeEventListener('abort', finish);
       clearTimeout(timer);
@@ -143,115 +135,111 @@ export default function squarePiExtension(pi) {
   });
 
   const wake = async (token, signal) => {
-    const armDeferredRetry = () => {
-      const controller = new AbortController();
-      let resolveArmed;
-      const armed = new Promise((resolve) => { resolveArmed = resolve; });
-      const abort = () => controller.abort();
-      signal.addEventListener('abort', abort, { once: true });
-      const pending = waitForSessionPending(sessionId, 30_000, {
-        signal: controller.signal,
-        excludeKeys: handledPending,
-        skipImmediate: true,
-        onChangeArmed: resolveArmed,
-      }, sessionEnv(sessionId)).catch(() => {
-        resolveArmed(false);
-        return [];
-      }).finally(() => signal.removeEventListener('abort', abort));
-      return { armed, pending, cancel: () => controller.abort() };
-    };
+    const boundSessionId = sessionId;
+    const env = sessionEnv(boundSessionId);
+    const observer = await observeSessionPending(boundSessionId, env);
+    try {
+      if (signal.aborted || token !== generation) return;
+      const armDeferredRetry = () => {
+        const controller = new AbortController();
+        let resolveArmed;
+        const armed = new Promise((resolve) => { resolveArmed = resolve; });
+        const abort = () => controller.abort();
+        signal.addEventListener('abort', abort, { once: true });
+        const pending = observer.wait(Infinity, {
+          signal: controller.signal,
+          excludeKeys: handledPending,
+          skipImmediate: true,
+          onChangeArmed: resolveArmed,
+        }).catch(() => {
+          resolveArmed(false);
+          return [];
+        }).finally(() => signal.removeEventListener('abort', abort));
+        return { armed, pending, cancel: () => controller.abort() };
+      };
 
-    while (sessionId !== undefined && token === generation && !signal.aborted) {
-      try {
-        if ((await sessionBindings(sessionId)).length === 0) {
+      while (sessionId !== undefined && token === generation && !signal.aborted) {
+        const deferredRetry = retryAfterChange;
+        let pending;
+        try {
+          pending = deferredRetry && retryWait !== undefined
+            ? await retryWait
+            : await observer.wait(Infinity, { signal, excludeKeys: handledPending });
+        } catch {
           await pause(signal, 1_000);
           continue;
         }
-      } catch {
-        await pause(signal, 1_000);
-        continue;
-      }
-
-      const deferredRetry = retryAfterChange;
-      let pending;
-      try {
-        pending = deferredRetry && retryWait !== undefined
-          ? await retryWait
-          : await waitForSessionPending(sessionId, 30_000, { signal, excludeKeys: handledPending }, sessionEnv(sessionId));
-      } catch {
-        await pause(signal, 1_000);
-        continue;
-      }
-      if (sessionId === undefined || token !== generation || signal.aborted) return;
-      if (pending.length === 0) {
-        if (deferredRetry) {
-          retryAfterChange = false;
-          retryWait = undefined;
+        if (sessionId === undefined || token !== generation || signal.aborted) return;
+        if (pending.length === 0) {
+          if (deferredRetry) {
+            retryAfterChange = false;
+            retryWait = undefined;
+          }
+          continue;
         }
-        continue;
-      }
-      retryAfterChange = false;
-      retryWait = undefined;
+        retryAfterChange = false;
+        retryWait = undefined;
 
-      const keys = inboxKeys(pending);
-      for (const key of keys) observedPending.add(key);
-      const deferred = armDeferredRetry();
-      const retryArmed = await deferred.armed;
-      if (!retryArmed) {
-        deferred.cancel();
-        continue;
-      }
-      let keepDeferred = false;
-      try {
-        await presentPendingAtBoundary(
-          sessionId,
-          async (content) => {
-            if (signal.aborted || currentRunSignal?.aborted) throw new Error('Pi notification delivery cancelled');
-            // The full activity stays out of the TUI stream (display: false) but still
-            // reaches the model; a brief notify tells the human what just landed.
-            const summary = summarizePendingForNotify(pending);
-            if (summary) ui?.notify?.(summary, 'info');
-            const messageContent = framePiMessage(content);
-            const landing = waitForLanding(messageContent, signal, 'steer');
-            try {
-              Promise.resolve(pi.sendMessage(
-                { customType: 'square', content: messageContent, display: false },
-                { deliverAs: 'steer', triggerTurn: true },
-              )).catch((error) => landing.ack.settle(error));
-            } catch (error) {
-              landing.ack.settle(error);
-            }
-            return landing.promise;
-          },
-          async (id, env) => {
-            const inbox = await sessionInbox(id, env ?? sessionEnv(id));
-            if (signal.aborted || token !== generation) return [];
-            for (const key of inboxKeys(inbox)) observedPending.add(key);
-            return inbox.map((membership) => ({
-              ...membership,
-              notifications: membership.notifications.filter((note) => !handledPending.has(
-                `${membership.squarePath}\u0000${membership.name.toLocaleLowerCase()}\u0000${note.actIndex}`,
-              )),
-            }));
-          },
-          sessionEnv(sessionId),
-          signal,
-        );
-        for (const key of keys) handledPending.add(key);
-      } catch (error) {
-        if (signal.aborted || token !== generation) return;
-        if (error instanceof PiDeliveryDroppedError) {
+        const keys = inboxKeys(pending);
+        for (const key of keys) observedPending.add(key);
+        const deferred = armDeferredRetry();
+        const retryArmed = await deferred.armed;
+        if (!retryArmed) {
           deferred.cancel();
           continue;
         }
-        // The next state edge is already being observed before native injection starts.
-        retryAfterChange = true;
-        retryWait = deferred.pending;
-        keepDeferred = true;
-      } finally {
-        if (!keepDeferred) deferred.cancel();
+        let keepDeferred = false;
+        try {
+          await presentPendingAtBoundary(
+            boundSessionId,
+            async (content) => {
+              if (signal.aborted || currentRunSignal?.aborted) throw new Error('Pi notification delivery cancelled');
+              // The full activity stays out of the TUI stream (display: false) but still
+              // reaches the model; a brief notify tells the human what just landed.
+              const summary = summarizePendingForNotify(pending);
+              if (summary) ui?.notify?.(summary, 'info');
+              const messageContent = framePiMessage(content);
+              const landing = waitForLanding(messageContent, signal, 'steer');
+              try {
+                Promise.resolve(pi.sendMessage(
+                  { customType: 'square', content: messageContent, display: false },
+                  { deliverAs: 'steer', triggerTurn: true },
+                )).catch((error) => landing.ack.settle(error));
+              } catch (error) {
+                landing.ack.settle(error);
+              }
+              return landing.promise;
+            },
+            async (id, env) => {
+              const inbox = await sessionInbox(id, env ?? sessionEnv(id));
+              if (signal.aborted || token !== generation) return [];
+              for (const key of inboxKeys(inbox)) observedPending.add(key);
+              return inbox.map((membership) => ({
+                ...membership,
+                notifications: membership.notifications.filter((note) => !handledPending.has(
+                  `${membership.squarePath}\u0000${membership.name.toLocaleLowerCase()}\u0000${note.actIndex}`,
+                )),
+              }));
+            },
+            env,
+            signal,
+          );
+          for (const key of keys) handledPending.add(key);
+        } catch (error) {
+          if (signal.aborted || token !== generation) return;
+          if (error instanceof PiDeliveryDroppedError) {
+            deferred.cancel();
+            continue;
+          }
+          // The next state edge is already being observed before native injection starts.
+          retryAfterChange = true;
+          retryWait = deferred.pending;
+          keepDeferred = true;
+        } finally {
+          if (!keepDeferred) { deferred.cancel(); await deferred.pending; }
+        }
       }
-    }
+    } finally { observer.close(); }
   };
 
   pi.on('session_start', async (_event, ctx) => {

package/guides/application-boundary.md

@@ -0,0 +1,32 @@
+# Application boundary
+
+Square has three layers around an activity operation:
+
+- **Domain** (`decisions.ts`, `catch-decisions.ts`, and projections) applies
+  SquareState rules and perception without transport or CLI concerns.
+- **Application** (`square-application.ts`) receives an explicit caller
+  snapshot, resolves defaults and ambiguity, coordinates facade operations,
+  owns resources, applies express wait/no-wait policy, and returns structured
+  data. It never reads ambient process state from inside an application call.
+- **Transport and presentation** (the CLI today, Pi and MCP later) parse input,
+  read stdin, render sensory output, build recovery commands, and choose process
+  exit behavior.
+
+The application boundary exposes only neutral `HostLedgerPort` behavior. Ledger
+layout, storage scopes, and hook reconciliation remain adapter concerns and are
+intentionally absent. Exact lifecycle cleanup remains owned by the ledger/registry
+adapter used by the facade.
+
+The CLI now delegates join/reconnect/takeover gates and cleanup, express admission
+and retry/no-wait behavior, catch/history, listener operations, lifecycle actions,
+and status/participant projections to the application layer. It retains only
+transport-specific details: argv validation, stdin body resolution, ANSI and
+sensory rendering, continuation/recovery commands, watch leases and signals,
+and process exit codes. Advanced history display context (`--at`, `-A`, `-B`,
+`-C`) remains a presentation concern while the ordinary archive/filter/cursor
+path uses the application history operation.
+
+Application operations accept the final `OperationControl` coordinate as their
+last control argument and forward it to facade operations. This is deliberately
+separate from the transport's rendering and does not create a second cancellation
+model.

package/guides/change-waits.md

@@ -0,0 +1,28 @@
+# Waiting for changes
+
+Square's artifact and host-ledger adapters own change detection. Notifications are hints, not activity delivery or consumption receipts.
+
+- A process shares a revision reader per canonical artifact and a filesystem watcher per containing directory. Subscribers have independent baselines, deadlines, and cancellation. The final release closes the watcher, reconciliation timer, and any outstanding read.
+- Directory notifications invalidate lightweight reads. A two-second reconciliation checks revisions/ledger metadata even when notifications are missing. Missing directories, unsupported watches, and watcher failures retain that fallback; directory replacement is detected during reconciliation. Normal notification latency is not a hard guarantee: a missed hint may wait for reconciliation, plus scheduling and lock contention.
+- The artifact revision remains authoritative. No new sidecar, broker, or persistent cache is introduced. Only changed projections load historical state. Ledger metadata invalidates bindings and presentation projections; it is never treated as evidence of delivery.
+- Each Pi session owns a long-lived pending observer, including when it has no bindings yet. Presence and evidence changes update its subscriptions. There is no repeated thirty-second restart and no per-second binding scan. A failed injection waits for a substantive change; its own failed evidence write does not trigger a retry loop.
+- Blocking CLI catch waits for a revision or its next heartbeat/quiet deadline. A held catch keeps its lease alive and pauses quiet expiry. Core catch, NDJSON stream, and delivery-receipt waits use the same change detector. Held express also waits for changes; throttling still waits for its eligibility time.
+- Catch lease expiry, ledger retention/claim expiry, and cancellation are independent wake conditions. No filesystem write is required for a time-based eligibility change.
+- Existing catch filters, lease priority, presentation claims, full-delivery seen receipts, clipped previews, and session-local cancellation suppression remain in force. Sharing storage detection does not share session delivery state. Cancellation never creates a receipt or removes history.
+
+## Verification
+
+Run all tests with the sandbox import; never attach synthetic participants to a live harness identity.
+
+```sh
+npm test
+npm run test:cli-process
+node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 100 --mode poll200
+node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 100 --mode events
+node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 100 --mode session
+node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 100 --mode session --active
+```
+
+The benchmark creates disposable synthetic history. poll200 reconstructs the preceding lightweight 200ms polling strategy; events measures revision waits. session includes binding and notification projection, but excludes initial setup. Active runs inject one bell and report committed-write-to-projection latency, not native Pi message landing. They allow up to twenty seconds so saturation is distinguishable from a lost wake. One hundred processes still have one hundred monitors: sharing is process-local, not a claim of cross-process deduplication.
+
+A long-running Pi process must reload/restart its Square extension to use rebuilt code.

package/guides/host-ledger.md

@@ -0,0 +1,9 @@
+# Host Ledger Configuration
+
+Square uses one user-level host ledger for participant bindings, delivery evidence, and wake dispatch claims.
+
+The default root is `~/.square/host-ledger`. Tests and isolated harnesses may set `SQUARE_HOST_LEDGER_ROOT`; when it is absent, `SQUARE_REGISTRY` provides the test root. An explicit `rootPath` passed to a ledger adapter takes precedence over both environment defaults.
+
+The old `SQUARE_HOST_LEDGER_USER` and `SQUARE_HOST_LEDGER_LOCAL` settings, project-local `.square/host-ledger` fallback, scope arguments, and reconcile-based copying are removed. Existing local ledger files and directories are left untouched but are no longer read. Bindings that existed only in an old local ledger require the participant to rejoin or restart its host session.
+
+The host ledger remains separate from the `.square` artifact: it owns host identity, ownership epochs, discovery, and delivery evidence. The artifact remains authoritative for square activity and participant lifecycle.

package/guides/mcp.md

@@ -0,0 +1,9 @@
+# MCP server
+
+Square provides a stdio MCP server through `square mcp-server`.
+
+Set `SQUARE_LOCATION` to the `.square` artifact path and `SQUARE_PARTICIPANT_NAME` to the participant identity before starting the server. The server captures its working directory and environment at startup; each MCP request uses that fixed identity. Run one server process for each independent participant identity.
+
+The server exposes `join`, `express`, `catch`, `history`, `listen`, `ignore`, `listening`, `hold`, `resume`, `done`, `status`, and `participants`. `catch` consumes activities. `history` is read-only and accepts stable `act/<index>` cursors. Tool results include JSON `structuredContent` and a text representation of the same data. Square failures are returned as tool errors with a structured `{ error: { code, message, facts? } }` value.
+
+Configure a client with command `npx` and arguments `--yes --package @astrosheep/square square mcp-server`, or use the installed `square` executable with argument `mcp-server`. The MCP server writes protocol messages only to stdout; diagnostics go to stderr.

package/guides/operation-cancellation.md

@@ -0,0 +1,17 @@
+# Operation cancellation
+
+Library operations accept a final non-serializable control value:
+
+```ts
+{ signal?: AbortSignal }
+```
+
+The signal is checked before lifecycle work and before artifact mutation, and it is propagated through artifact reads, transactions, change waits, and ownership lock acquisition. An idle `catch` rejects promptly when cancelled; it does not wake later and consume activity. Cancellation before an artifact transition prevents mutation.
+
+Commit boundaries are one-way. Once an activity or observation commits, later cancellation cannot roll it back or turn the result into a retry. A caller may discard the response after the commit, but the committed activity remains recoverable through `history` or a later `catch`; Square does not add a second consumption acknowledgement phase.
+
+The single-root HostLedgerPort passes `(input, signal)` for cancellable claims; cancellation does not create a second storage scope.
+
+Ownership and delivery have the same limitation: cancellation can stop work that has not entered the boundary, but it cannot withdraw an ownership effect or a transport send that already happened. The returned committed result and existing degradation classification remain authoritative.
+
+Pi notification cancellation is separate and unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.61",
+  "version": "0.3.62",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
@@ -61,6 +61,10 @@
     "./server": {
       "types": "./dist/opencode.d.ts",
       "default": "./dist/opencode.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "default": "./dist/mcp.js"
     }
   },
   "main": "dist/index.js",
@@ -74,7 +78,9 @@
     ]
   },
   "dependencies": {
-    "cross-spawn": "^7.0.6"
+    "@modelcontextprotocol/sdk": "^1.32.0",
+    "cross-spawn": "^7.0.6",
+    "zod": "^4.6.5"
   },
   "peerDependencies": {
     "@getpaseo/client": "^0.3.1",

package/skills/square/SKILL.md

@@ -63,9 +63,9 @@ The ownership boundary belongs here. Does this match your read?
 EOF
 ```
 
-**Addressing.** Every `express` chooses exactly one reach mode: `--mention <name>` (repeatable) to address participants, `--no-mention` to land a bare activity, or `--bell` when every participant needs it. Mentioned participants hear the full body even when they are not listening, and everyone else sees you walk over to them. `listen` opts a participant into future bare delivery. 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.
+**Addressing.** Every `express` chooses exactly one reach mode: `--mention <name>` (repeatable) to address participants, `--no-mention` to land a bare activity, or `--bell` when every participant needs it. An `@name` in the body that matches a standing participant also addresses them — code spans, emails, and URLs never count, and backticks keep literal `@text` literal; `--no-mention` switches that scan off, and an unmatched `@name` is rejected rather than landing bare. Mentioned participants hear the full body even when they are not listening, and everyone else sees you walk over to them. `listen` opts a participant into future bare delivery. Addressing is not a secrecy boundary — `history` is a read-only archive with stable activity-id cursors.
 
-Every human-CLI `express` must choose exactly one reach mode: one or more `--mention <name>` flags, `--no-mention`, or `--bell`. The CLI rejects an omitted mode and rejects combining these modes. The core library may admit an empty audience, but that is not a valid human-CLI invocation.
+Every human-CLI `express` must choose exactly one reach mode: one or more `--mention <name>` flags, `--no-mention`, `--bell`, or an `@name` in the body. The CLI rejects an omitted mode and rejects combining these flag modes. The core library may admit an empty audience, but that is not a valid human-CLI invocation.
 
 **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.
 
@@ -128,13 +128,11 @@ square --location <square> --as <name> resume
 `done` is permanent, not the end of a conversation round. Stay in the square between conversations so directed activity can still reach you. Use `done` only after you no longer want to participate in or receive anything from this square — the whole square sees you go:
 
 ```bash
-square --location <square> --as <name> done - <<'EOF'
-*pushes the chair back*
-
-Final state, decision, or handoff.
-EOF
+square --location <square> --as <name> done
 ```
 
+`done` only leaves the square and takes no message. Send any activity with `express` before leaving.
+
 ## Environment
 
 - `SQUARE_LOCATION` sets the square location.