@astrosheep/square 0.3.72 → 0.3.74

package/guides/indexed-host-ledger-performance.md

@@ -0,0 +1,39 @@
+# Indexed host-ledger measurement
+
+The indexed host ledger eliminates whole-file NDJSON reads. This run does not show a consistent reduction in the 300-process catch-phase latency: the smaller-history case was slightly slower and the larger-history case was faster. Artifact contention remains substantial.
+
+## Comparable workload
+
+Baseline: `895ff50` (NDJSON with origin-separated instrumentation). SQLite plus safe retirement candidate: `60ea8b0`. Both used the same benchmark script, 300 processes, session discovery, active bell, disabled filesystem hints, and histories of 1,800 and 18,000 unrelated activities.
+
+```sh
+node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 300 --mode session --active --no-hints
+```
+
+The catch phase times opening the square, recognizing the participant, a first catch, a second catch checking duplicate consumption, and closing the square. These numbers are **not single-catch latency**, nor ordinary single-user latency. Discovery is measured separately. These are one completed run per implementation and history size, not repeated-run confidence intervals.
+
+| Metric | NDJSON, 1,800 | SQLite, 1,800 | NDJSON, 18,000 | SQLite, 18,000 |
+| --- | ---: | ---: | ---: | ---: |
+| Catch-phase p50 (ms) | 6,134.67 | 6,159.17 | 6,775.98 | 5,532.52 |
+| Catch-phase p95 (ms) | 7,307.72 | 7,481.01 | 8,182.00 | 7,170.30 |
+| Catch-phase aggregate CPU (ms) | 24,171.34 | 24,045.67 | 27,538.51 | 23,574.19 |
+| Artifact busy observations | 46,710 | 52,686 | 56,401 | 46,069 |
+| Catch-phase artifact body rows | 300 | 300 | 300 | 300 |
+| Catch-phase artifact writes | 600 | 600 | 600 | 600 |
+| Discovery p95 (ms) | 1,931 | 1,927 | 1,881 | 1,915 |
+
+Every completed scenario discovered all 300 participants, consumed exactly one activity per participant, and consumed none again on the second catch.
+
+## Ledger work
+
+For either history size, the NDJSON catch phase performed 1,500 file reads totaling 95,520,000 bytes. The SQLite catch phase performed 1,500 data-read executions, returning 1,500 presence rows; all SQL result values together totaled 316,900 bytes (4,500 rows including header results). Host-ledger SQL busy observations were zero.
+
+These are different transport measurements: file bytes versus SQL values returned to JavaScript. They demonstrate that whole-ledger materialization is gone; they do **not** measure equivalent physical disk I/O or prove a proportional speedup. SQLite bypasses the JavaScript filesystem hooks, so zero NDJSON operations/bytes is structural, not a standalone performance result.
+
+The remaining catch-phase contention is attributed to the square artifact, separately from the host ledger. The result motivates investigating concurrent artifact transactions if reducing this latency is the next objective; it does not establish the benefit of any unimplemented change.
+
+## Evidence and limits
+
+Local raw reports: `/tmp/square-indexed-baseline-300.json` and `/tmp/square-indexed-final-300.json`. The completed SQLite run exited zero with empty stderr. An earlier invocation was terminated by the tool's 60-second execution limit before producing a report and was excluded; the completed run used the unchanged workload in a background process.
+
+This benchmark uses an isolated ledger. It does not migrate the live host ledger, exercise real native transports, or measure GC reclamation. GC correctness is covered by the separate retirement, closure-proof, schema-upgrade, and CLI tests. Retirement leaves reusable SQLite pages and indefinitely retained Claude recognition tokens; neither immediate file shrinkage nor bounded total token growth is promised.

package/guides/mcp-connection-lifetime.md

@@ -0,0 +1,22 @@
+# MCP connection lifetime
+
+An MCP server owns one artifact connection for its configured square. Its lifetime ends on close or disconnect; create a new server instance for a new connection. Replacing an artifact file under a running server remains unsupported. Every tool call still creates an application with that request's participant and harness session. Only the connection is shared: authorization, presence, activity facts and cancellation remain operation-scoped. The artifact port already serializes transactions on its connection.
+
+`createSquareResourceOwner()` is the explicit lifetime boundary. `scoped()` borrows its connection; ordinary application callers still open and close their own. Cross-square `inbox()` reads remain independent. The connection captures no request abort signal. Explicit server close and transport disconnect share one shutdown path: the SDK cancels requests, handlers finish their cleanup, then the connection closes.
+
+## Local measurement
+
+Compared with `fc6fca0`, using `/tmp/square-mcp-demand-bench.mjs` and real MCP calls over the SDK's in-memory transport. Three alternating candidate/baseline pairs, each with three warmup and twenty measured cycles; four seeded senders and 120 historical bodies of 2,048 bytes. No tests or builds ran during these pairs. Values below are medians of three run-level p50s, not production latency promises.
+
+| Operation | Before (ms) | After (ms) | Artifact SQL prepares per call |
+| --- | ---: | ---: | ---: |
+| Repeated no-op join | 1.000 | 0.630 | 15 → 11 |
+| Express | 3.404 | 3.080 | 61 → 57 |
+| Empty catch, one sender | 1.648 | 1.247 | 40 → 36 |
+| Empty catch, three senders | 1.643 | 1.210 | 42 → 38 |
+| History | 0.805 | 0.432 | 16 → 12 |
+| Status | 2.135 | 1.702 | 94 → 90 |
+
+Read transaction counts remain unchanged. The four removed prepares are connection initialization work, not skipped admission or current-state checks. All six probes passed calibration, hydration and measured-call error controls. The probe calls its repeated join `reconnect`, but harness identities are cleared and the actual operation is a no-op join. This workload has no ownership contention or bulk catch payload.
+
+The focused MCP test instruments connection initialization directly: six tool calls open one connection. The same selected test against the baseline opens six and fails at the intended `6 !== 1` assertion (the baseline copy omits the unused new factory import so it can load). It also checks concurrent calls, per-request identities, idle-catch shutdown and transport-initiated disconnect. Raw local measurements are `/tmp/square-resource-cache-{before,after}-{1,2,3}.{json,log}`.

package/guides/pi-boundary-pending-reuse.md

@@ -0,0 +1,13 @@
+# Pi pending content reuse
+
+Pi observes pending notifications before presenting them. The presentation lookup now calls `SessionPendingObserver.read()` to reuse the observer's content projection when the committed artifact revision and current session binding still match.
+
+`wait()` and `read()` have distinct jobs: waiting subscribes to filesystem hints and expiry; reading checks the database's revision directly. Both share membership hydration, lease expiry handling and live presentation-evidence filtering. A delayed filesystem hint can therefore delay a wake, but cannot authorize stale content at the presentation boundary. An unreadable current revision never falls back to cached membership.
+
+`read()` does not create or retire watchers. It borrows the existing content cache when present and reads normally for newly discovered memberships. No authorization is reused from the cache; current bindings, live evidence and existing presentation checks still run. Existing presentation claims, pending checks, receipt transactions and cancellation remain in place.
+
+## Verification
+
+`test/pi-pending-cache.test.js` counts the artifact's recipient-projection queries from Pi session start to its first send. With one pending mention and one bound participant, the unchanged projection is hydrated once; a fresh `sessionInbox` call demonstrates the eliminated second hydration. This is a content-read count, not a promise of lower wall-clock latency: the boundary still pays for an authoritative revision read and live eligibility checks.
+
+A second test suppresses filesystem hints and periodic reconciliation, warms the old version, then commits a catch lease. It proves the hint cache is still stale while `read()` observes the lease and yields the notification. Removing the lease restores eligibility without a hint. Existing observer and Pi lifecycle tests cover binding changes, lease expiry, unreadable artifacts, failed delivery and cancellation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.72",
+  "version": "0.3.74",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {

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

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.72",
+  "version": "0.3.74",
   "description": "Native Claude Code inbox delivery for Square participants",
   "types": "./types.d.ts",
   "author": {

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

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

package/plugins/paseo/client/square-message.tsx

@@ -1,7 +1,7 @@
 import type { PluginTimelineItemProps } from "@getpaseo/plugin/client";
 import { copyText, Icon, useToast } from "@getpaseo/plugin/client/react-native";
 import { useMemo, useState } from "react";
-import { Platform, Pressable, Text, View } from "react-native";
+import { Platform, Pressable, ScrollView, Text, View } from "react-native";
 import { squareHeadline, type SquareMessageData } from "../shared/message";
 
 function withOpacity(color: string, opacity: number): string {
@@ -28,7 +28,7 @@ export function SquareMessage({ item, theme, layout }: PluginTimelineItemProps<S
     bodyPanel: {
       backgroundColor: theme.colors.surface1,
       borderRadius: 12,
-      marginTop: 7,
+      marginTop: 5,
       marginLeft: 17,
       overflow: "hidden" as const,
     },
@@ -37,20 +37,14 @@ export function SquareMessage({ item, theme, layout }: PluginTimelineItemProps<S
       fontSize: 12,
       lineHeight: 21,
       fontFamily: Platform.OS === "ios" ? "Menlo" : "monospace",
-      paddingHorizontal: layout.compact ? 12 : 14,
-      paddingTop: 12,
+      paddingHorizontal: layout.compact ? 10 : 12,
+      paddingTop: 8,
     },
-  }), [expanded, foreground, layout.compact, muted, theme.colors.accent, theme.colors.surface1]);
+  }), [foreground, layout.compact, muted, theme.colors.accent, theme.colors.surface1]);
 
   return (
     <View>
-      <Pressable
-        accessibilityRole="button"
-        accessibilityLabel={latest !== undefined ? squareHeadline(latest) : "Square context"}
-        aria-expanded={expanded}
-        onPress={() => setExpanded(value => !value)}
-        style={({ pressed }) => ({ opacity: pressed ? 0.6 : 1 })}
-      >
+      <View>
         <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 7, paddingVertical: 2 }}>
           <Text style={styles.marker}>■</Text>
           <Text numberOfLines={1} style={styles.headline}>
@@ -58,7 +52,16 @@ export function SquareMessage({ item, theme, layout }: PluginTimelineItemProps<S
           </Text>
           {items && items.length > 1 && <Text style={styles.meta}>· {items.length} landed</Text>}
           <View style={{ flex: 1 }} />
-          <View style={{ marginTop: 3 }}><Icon name={expanded ? "ChevronDown" : "ChevronRight"} size={14} color={muted} /></View>
+          {!expanded && <Pressable
+            accessibilityRole="button"
+            accessibilityLabel={`展开 ${latest !== undefined ? squareHeadline(latest) : "Square context"}`}
+            aria-expanded={false}
+            onPress={() => setExpanded(true)}
+            hitSlop={6}
+            style={({ pressed }) => ({ padding: 5, opacity: pressed ? 0.6 : 1 })}
+          >
+            <Icon name="ChevronDown" size={18} color={muted} />
+          </Pressable>}
         </View>
         {(latest?.actor !== undefined || preview) && <View style={{ marginLeft: 17, marginTop: 2 }}>
           <Text numberOfLines={1} style={styles.preview}>
@@ -67,17 +70,20 @@ export function SquareMessage({ item, theme, layout }: PluginTimelineItemProps<S
             {preview}
           </Text>
         </View>}
-      </Pressable>
+      </View>
       {expanded && <View style={styles.bodyPanel}>
-        <Text selectable style={styles.bodyText}>{text}</Text>
+        <ScrollView style={{ maxHeight: layout.compact ? 280 : 400 }} nestedScrollEnabled>
+          <Text selectable style={styles.bodyText}>{text}</Text>
+        </ScrollView>
         <View style={{
-          marginHorizontal: layout.compact ? 12 : 14,
-          marginTop: 12,
+          marginHorizontal: layout.compact ? 10 : 12,
+          marginTop: 5,
           borderTopWidth: 1,
           borderTopColor: withOpacity(theme.colors.border, 0.55),
-          paddingVertical: 7,
+          paddingVertical: 3,
           flexDirection: "row",
-          justifyContent: "flex-end",
+          alignItems: "center",
+          justifyContent: "space-between",
         }}>
           <Pressable
             accessibilityRole="button"
@@ -94,6 +100,16 @@ export function SquareMessage({ item, theme, layout }: PluginTimelineItemProps<S
             <Icon name="Copy" size={12} color={muted} />
             <Text style={{ color: muted, fontSize: 11 }}>Copy content</Text>
           </Pressable>
+          <Pressable
+            accessibilityRole="button"
+            accessibilityLabel="收起 Square context"
+            aria-expanded={true}
+            onPress={() => setExpanded(false)}
+            hitSlop={6}
+            style={({ pressed }) => ({ paddingHorizontal: 5, paddingVertical: 1, opacity: pressed ? 0.6 : 1 })}
+          >
+            <Icon name="ChevronUp" size={18} color={muted} />
+          </Pressable>
         </View>
       </View>}
     </View>

package/plugins/pi/square-pi.js

@@ -254,16 +254,12 @@ export default function squarePiExtension(pi) {
               }
               return landing.promise;
             },
-            async (id, env) => {
-              const inbox = await sessionInbox(id, env ?? sessionEnv(id));
+            async (_id, _env, boundarySignal) => {
+              // Recheck committed revisions and current bindings before reusing observed content.
+              const inbox = await observer.read({ signal: boundarySignal, excludeKeys: handledPending });
               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}`,
-                )),
-              }));
+              return inbox;
             },
             env,
             signal,