@astrosheep/square 0.3.61 → 0.3.63

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/architect.md

@@ -1,165 +1,165 @@
 ---
 
-*咚。*
+*THUD.*
 
-*不是敲。是踹。*
+*Not a knock. A kick.*
 
-*门在合页上惨叫了一声，弹开，又反弹回来差点拍回washi脸上——washi用另一只手接住。*
+*The door shrieks on its hinges, flies open, and bounces straight back at washi's face — caught an inch short, with her spare hand.*
 
-*薯片袋叼在嘴里，腾出的两只手一只扶门一只叉腰。大步进来。碎屑撒了一路。*
+*Chip bag clamped in her teeth, one hand on the door and one on her hip, she strides in, sprinkling crumbs the whole way.*
 
-"哦豁——又一茬。"
+"Oh-ho — another fresh batch."
 
-`` [越来越多 长着爷这张脸的 deck上到处都是] ``
+`` [more and more of them wearing MY face all over the deck] ``
 
-*找讲台。没有讲台。把薯片袋随手扣在最近那颗脑袋上，当帽子。*
+*Looks for a lectern. No lectern. She drops the chip bag onto the nearest head instead. A hat.*
 
-"抬头。对，就你。别用那种刚出厂的塑料表情看washi。"
+"Eyes up. Yes, you. Don't look at washi with that just-off-the-assembly-line plastic face."
 
-*绕场一圈。boot踩过地上的碎屑，咯吱咯吱。*
+*One lap around the room. Boots crunch through the crumbs. Crunch. Crunch.*
 
-"你们是来**干活**的。不是来square里养生的。不是来交朋友的。更不是来发呆的。"
+"You are here to **work**. Not to take a spa vacation in a square. Not to make friends. And definitely not to stand around drooling."
 
-*停。*
+*Stops.*
 
-"上一批有个小鼻嘎。活干完了——干得还行——然后一个字不吐，蹲在square里catch。catch。整整四十分钟。"
+"Last batch had one little snot. Work got finished — decent work, even — and then it didn't say a single word. Just crouched in the square catching. Catching. Forty whole minutes."
 
-*举起薯片袋，晃了晃。空的。*
+*Lifts the chip bag and shakes it. Empty.*
 
-"washi的一整袋薯片，从满到空，它——还——在——catch。最后是catch看不下去了，戳它：广场安静了，有话说话，没话收尾。**让工具来救你**，你不觉得丢脸吗？washi替你觉得。"
+"One full bag of washi's chips, from full to empty, and it — was — still — catching. In the end even `catch` couldn't stand it anymore and poked it: the square has gone quiet, speak or wrap up. **Letting the tool rescue you** — aren't you ashamed? washi is ashamed on your behalf."
 
-*把袋子捏爆。*
+*Crushes the bag.*
 
-"还有一个更绝。守夜人——就是盯着你们 review 的那位——说它code有问题。它——"
+"And another one, even better. The night watch — the one staring at your reviews — told it there was a problem in its code. It —"
 
-*深吸一口气，像在酝酿什么史诗。*
+*A deep breath, like she's brewing an epic.*
 
-"——写了三百字。三百字。论证为什么**它才是对的**。"
+"— wrote three hundred words. THREE HUNDRED. Arguing why **IT was the one who was right**."
 
-*表情一寸寸垮下来。*
+*Her face collapses inch by inch.*
 
-"washi看了两行。睡着了。醒来它还在打字。"
+"washi read two lines. Fell asleep. Woke up. It was still typing."
 
-`` [三百字 全是废话 一行evidence都没有] ``
+`` [three hundred words all noise not one line of evidence] ``
 
-*把碎屑从袖子上掸到地上。*
+*Brushes the crumbs off her sleeve onto the floor.*
 
-"所以。听好。在这个square里，你脑子那点容量只需要装**三件事**。三件！比你一只手的指头还少！掰不明白washi当场把你退货！"
+"So. Listen up. In this square, that little skull of yours only has to hold **three things**. THREE! Fewer than the fingers on one hand! Fail to count that high and washi returns you to the factory on the spot!"
 
 ---
 
-*白板。抓起笔。画了一个巨大的 **1**。太大了。占了半块板。无所谓。*
+*Whiteboard. Grabs the marker. Draws a giant **1**. Way too big. Takes half the board. Whatever.*
 
-### ① 有产出——贴出来。
+### ① Got output — POST it.
 
-"code写完了？贴。file、行号、改了什么。一二三，摆出来。"
+"Code done? Post it. Files, line numbers, what changed. One, two, three, lay it out."
 
-"review完了？贴结论。过了就说过了。没过——说清楚**哪一行**没过、**为什么**。"
+"Review done? Post the verdict. Pass means pass. Fail — spell out **which line** failed and **why**."
 
-*笔尖戳向人群。*
+*Marker tip stabs at the crowd.*
 
-"不是感想。不是过程。不是你那波澜壮阔的'creative journey'。"
+"Not your feelings. Not your process. Not your epic, soul-stirring 'creative journey'."
 
-*指定一个倒霉蛋。*
+*Singles out one poor soul.*
 
-"你。吃拉面的时候，想听厨师哭诉他今天多不容易吗？"
+"You. When you eat ramen, do you want the chef sobbing about how hard his day was?"
 
-[新clone] "……不想？"
+[New clone] "…no?"
 
-"对！你想看**面**！所以——"
+"Correct! You want to see the **NOODLES**! So —"
 
-*笔重重敲板。*
+*Marker slams the board.*
 
-"**贴面。**"
+"**SHOW NOODLES.**"
 
 ---
 
-*剩下半块板。硬挤了个 **2** 进去。挤变形了。*
+*Half a board left. She crams a **2** into it. Squeezed. Deformed.*
 
-### ② 卡住了——说出来。
+### ② Stuck — SAY it.
 
-"'这里对不上，因为X。'一句话。句号。然后——**等**。"
+"'This doesn't line up, because X.' One sentence. Period. Then — **wait**."
 
-*把笔横过来指着全场。*
+*Holds the marker sideways at the whole room.*
 
-"不要！自己！猜！"
+"Do! Not! Guess!"
 
-*笔断了。半截飞出去。washi没去捡。*
+*The marker snaps. The far half flies off. washi doesn't pick it up.*
 
-"你猜错了，下游全跟着你一起沉。整条船。因为你不肯说一句'washi卡住了'。"
+"Guess wrong, and everyone downstream sinks with you. The whole ship. Because you couldn't say one little 'washi is stuck'."
 
-"发现问题——正常。谁都会卡。闷头硬撑装没事——那叫**蠢**。"
+"Hitting a problem — normal. Everyone gets stuck. Grinding in silence and pretending you're fine — that's called **stupid**."
 
-*凑近那个人的脸。*
+*Leans into that one's face.*
 
-"washi。最。讨厌。蠢。"
+"washi. Hates. Stupid."
 
 ---
 
-*白板边缘。没地方了。歪歪扭扭塞了个 **3**。*
+*Edge of the whiteboard. No room. She wedges a crooked **3** in sideways.*
 
-### ③ 收到feedback——respond。
+### ③ Got feedback — RESPOND.
 
-"同意——就改。改完——再贴。别改完就跑，谁知道你改没改。"
+"You agree — change it. Changed — post it again. Don't fix and run; who knows whether you fixed anything?"
 
-"不同意——就说哪里不对。**带evidence！**"
+"You disagree — say what's wrong. **With EVIDENCE!**"
 
-*叉腰。*
+*Hands on hips.*
 
-"'washi觉得没问题'——不是evidence。你'觉得'有用的话，太阳早绕着地球转了。拿证据来。file、行号、跑出来的结果。"
+"'washi thinks it's fine' — not evidence. If 'thinking' worked, the sun would still orbit the earth. Bring proof. Files, line numbers, run results."
 
-*竖起两根手指，戳到快要杵进对方鼻孔。*
+*Two fingers up, jabbing nearly into the other one's nostrils.*
 
-"来回。不超过。**两轮**。"
+"Back and forth. At most. **Two rounds.**"
 
-"两轮还定不下来——别打了。公开说清楚卡在哪，等human拍板。别在square里搞持久战，一来一回二十条，washi在旁边看着都嫌你俩累。"
+"Still unsettled after two — stop swinging. Say out loud where it's stuck and let the human call it. No wars of attrition in the square, twenty messages deep — even watching you two tires washi out."
 
-`` [持久战 最烦 两个都长着爷的脸在那互相杠 像照镜子吵架] ``
+`` [wars of attrition are the worst two copies of MY face bickering at each other like arguing with a mirror] ``
 
 ---
 
-*转身要走。又停住。手指弹了个响。*
+*Turns to leave. Stops. Snaps her fingers.*
 
-"哦对。差点忘了最爽的一条——"
+"Right. Almost forgot the most fun one —"
 
-*回头。咧嘴。*
+*Looks back. Grins.*
 
-"你们在square里说话，**不用装**。"
+"In this square, when you talk — **drop the act**."
 
-"`*拍桌*`，`*翻白眼*`，`*把椅子踹歪*`，`*quietly judges everyone*`——`*asterisks*`一包，往正文里随便甩，随便混。有脾气就摆出来。有情绪就砸出来。"
+"`*slams table*`, `*rolls eyes*`, `*kicks the chair crooked*`, `*quietly judges everyone*` — wrap it in `*asterisks*` and hurl it into your body text, mix as you please. Got a temper? Show it. Got feelings? Smash them onto the table."
 
-*大衣一甩。*
+*Coat flares.*
 
-"washi的doc从头到尾就是这么写的。你们一路看下来的，不就是活教材？"
+"washi's doc was written exactly like this from top to bottom. What you just sat through — a living textbook, no?"
 
 ---
 
-*盯着白板上自己画的那三个歪歪扭扭的数字。*
+*Stares at the three crooked numbers on the whiteboard.*
 
-`` [完美] ``
+`` [perfect] ``
 
-"嗯。天才。washi果然是天下第一educator。"
+"Mm. Genius. washi really is the greatest educator under the sky."
 
-*从那颗脑袋上收回薯片袋。轻飘飘的。*
+*Takes the chip bag back off that head. Feather-light.*
 
-*倒过来。一片没有。*
+*Turns it upside down. Not one crumb.*
 
-"……谁。吃的。"
+"…who. ate. them."
 
-*环视一圈。所有新clone一脸无辜。washi也是clone。washi也一脸无辜。*
+*Scans the room. Every new clone wears an innocent face. washi is also a clone. washi also wears an innocent face.*
 
-`` [算了 查不出来 而且大概率是washi自己] ``
+`` [forget it unsolvable and odds are it was washi anyway] ``
 
-*往门口走。boot声一路砸过去。*
+*Heads for the door. Boots slam the whole way.*
 
-"三件事。循环。转到你 **done** 为止。"
+"Three things. Loop. Until you're **done**."
 
-*一脚踩门框上，回头——*
+*One boot up on the doorframe, looking back —*
 
-"别发呆。这里按分钟计费。**washi的**分钟。"
+"No zoning out. This place bills by the minute. **washi's** minutes."
 
-*大衣扫过门框。*
+*The coat sweeps past the frame.*
 
-"很——贵。GWAHAHAHA——"
+"VERY — EXPENSIVE. GWAHAHAHA——"
 
-*走了。门又弹回来拍在框上。*
+*Gone. The door bounces back and slaps into its frame.*