@astrosheep/square 0.3.73 → 0.3.75

package/dist/square-facade.d.ts

@@ -1,6 +1,6 @@
 import type { ActivityId, Perception, Reach } from './square-core.js';
 import type { StoredAct } from './model.js';
-import type { HostLedgerPort, WakeTransportPort, DeliveryResult } from './ports.js';
+import type { HostLedgerPort, WakeTransportPort, DeliveryResult, SquareResourceOwner } from './ports.js';
 import type { DiagnoseResult } from './artifact.js';
 import type { MigrationOutcome } from './square-migration.js';
 export type { ActivityId, Perception, Reach } from './square-core.js';
@@ -136,10 +136,14 @@ export interface SquareApplicationContext extends Readonly<OpenOptions> {
     readonly env: NodeJS.ProcessEnv;
     readonly squarePath?: string;
     readonly participant?: string;
+    /** Borrow the owner's connection for the configured square. The caller owns its lifetime;
+     *  without an owner, each operation opens and closes its own connection. */
+    readonly resources?: SquareResourceOwner;
 }
-export interface ApplicationOutcome<Data, Projection> {
+/** Data-only callers do not request or pay for presentation work. */
+export interface ApplicationOutcome<Data, Projection, Presentation extends boolean = true> {
     readonly data: Data;
-    readonly projection: Projection;
+    readonly projection: Presentation extends true ? Projection : undefined;
 }
 export interface ApplicationFailureDetail {
     readonly operation: 'express' | 'join' | 'catch' | 'history' | 'other';
@@ -444,26 +448,26 @@ export interface StatusProjection extends SquareContextProjection, PresenceClass
 }
 export interface ParticipantsProjection extends SquareContextProjection, PresenceClassification {
 }
-export interface SquareApplication {
+export interface SquareApplication<Presentation extends boolean = true> {
     now(): number;
-    build(input: BuildApplicationInput, control?: OperationControl): Promise<ApplicationOutcome<BuildApplicationData, SquareContextProjection>>;
-    join(options?: JoinApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<JoinApplicationData, EntryProjection>>;
-    express(body: string, options?: ExpressApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<ExpressApplicationData, ExpressProjection>>;
-    catch(options?: CatchApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<CatchApplicationData, CatchProjection>>;
-    history(query?: HistoryApplicationQuery, control?: OperationControl): Promise<ApplicationOutcome<HistoryApplicationData, HistoryProjection>>;
-    listen(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection>>;
-    ignore(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection>>;
-    listening(control?: OperationControl): Promise<ApplicationOutcome<ListeningData, SquareContextProjection>>;
-    hold(reason?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection>>;
-    resume(control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection>>;
-    done(body?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection>>;
-    status(viewer?: string, control?: OperationControl): Promise<ApplicationOutcome<StatusApplicationData, StatusProjection>>;
-    participants(control?: OperationControl): Promise<ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection>>;
-    diagnose(control?: OperationControl): Promise<ApplicationOutcome<DiagnosisApplicationData, Partial<SquareContextProjection>>>;
-    migrate(control?: OperationControl): Promise<ApplicationOutcome<MigrationApplicationData, Partial<SquareContextProjection>>>;
-    discover(options: DiscoveryApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<DiscoveryApplicationData, DiscoveryProjection>>;
-    inbox(sessionId: string, options?: InboxApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<InboxApplicationData, InboxProjection>>;
-    recovery(control?: OperationControl): Promise<ApplicationOutcome<RecoveryApplicationData, RecoveryProjection>>;
+    build(input: BuildApplicationInput, control?: OperationControl): Promise<ApplicationOutcome<BuildApplicationData, SquareContextProjection, Presentation>>;
+    join(options?: JoinApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<JoinApplicationData, EntryProjection, Presentation>>;
+    express(body: string, options?: ExpressApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<ExpressApplicationData, ExpressProjection, Presentation>>;
+    catch(options?: CatchApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<CatchApplicationData, CatchProjection, Presentation>>;
+    history(query?: HistoryApplicationQuery, control?: OperationControl): Promise<ApplicationOutcome<HistoryApplicationData, HistoryProjection, Presentation>>;
+    listen(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection, Presentation>>;
+    ignore(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection, Presentation>>;
+    listening(control?: OperationControl): Promise<ApplicationOutcome<ListeningData, SquareContextProjection, Presentation>>;
+    hold(reason?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
+    resume(control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
+    done(body?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
+    status(viewer?: string, control?: OperationControl): Promise<ApplicationOutcome<StatusApplicationData, StatusProjection, Presentation>>;
+    participants(control?: OperationControl): Promise<ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection, Presentation>>;
+    diagnose(control?: OperationControl): Promise<ApplicationOutcome<DiagnosisApplicationData, Partial<SquareContextProjection>, Presentation>>;
+    migrate(control?: OperationControl): Promise<ApplicationOutcome<MigrationApplicationData, Partial<SquareContextProjection>, Presentation>>;
+    discover(options: DiscoveryApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<DiscoveryApplicationData, DiscoveryProjection, Presentation>>;
+    inbox(sessionId: string, options?: InboxApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<InboxApplicationData, InboxProjection, Presentation>>;
+    recovery(control?: OperationControl): Promise<ApplicationOutcome<RecoveryApplicationData, RecoveryProjection, Presentation>>;
     stream(options: StreamApplicationOptions, control?: OperationControl): AsyncIterable<StreamApplicationRecord>;
 }
 export type JoinApplicationResult = JoinApplicationData;

package/dist/views.d.ts

@@ -11,7 +11,7 @@ export declare const NON_READ: readonly ["join", "done", "say", "hold", "resume"
 export declare function toPublicActivity(stored: StoredAct): Activity;
 export declare function parseRequiredActivityId(id: ActivityId): number;
 /** Compile the public query directly to typed selectors; only search hydrates unselected bodies. */
-export declare function selectHistory(facts: SquareRead, query: HistoryApplicationQuery, limit: number | null, kinds: ActivityFilter['kinds']): {
+export declare function selectHistory(facts: SquareRead, query: HistoryApplicationQuery, limit: number | null, kinds: ActivityFilter['kinds'], presentation?: boolean): {
     continuation?: HistoryContinuation | undefined;
     activities: StoredAct[];
     visibleActivities: StoredAct[];
@@ -29,8 +29,10 @@ export declare function recoveryObservation(square: OpenSquare, name: string, co
 export declare function entryPresentation(square: OpenSquare, name: string, lastN?: number | null, control?: OperationControl): Promise<EntryPresentation>;
 type ParticipantQueryContext = Pick<SquareContextProjection, 'location' | 'now' | 'automaticDeliveryAvailable'>;
 export declare function queryParticipants(facts: SquareRead, context: ParticipantQueryContext): ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection>;
+export declare function queryParticipants(facts: SquareRead, context: ParticipantQueryContext, presentation: boolean): ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection, boolean>;
 export declare function listPresentation(square: OpenSquare, control?: OperationControl): Promise<ListPresentation>;
 export declare function queryStatus(facts: SquareRead, context: ParticipantQueryContext, viewer?: string): ApplicationOutcome<StatusApplicationData, StatusProjection>;
+export declare function queryStatus(facts: SquareRead, context: ParticipantQueryContext, viewer: string, presentation: boolean): ApplicationOutcome<StatusApplicationData, StatusProjection, boolean>;
 export declare function eventPresentation(square: OpenSquare, id: ActivityId, control?: OperationControl): Promise<EventPresentation>;
 export declare function catchPresence(square: OpenSquare, control?: OperationControl): Promise<CatchPresence>;
 export declare function streamProjection(square: OpenSquare, cursor: number, recipient?: string, control?: OperationControl): Promise<StreamProjection>;

package/dist/views.js

@@ -28,7 +28,7 @@ export function parseRequiredActivityId(id) {
     return index;
 }
 /** Compile the public query directly to typed selectors; only search hydrates unselected bodies. */
-export function selectHistory(facts, query, limit, kinds) {
+export function selectHistory(facts, query, limit, kinds, presentation = true) {
     if (query.before !== undefined && query.after !== undefined)
         throw new SquareError('invalid_args', 'History cannot combine before and after cursors');
     const afterIndex = query.after === undefined ? undefined : parseRequiredActivityId(query.after);
@@ -44,14 +44,16 @@ export function selectHistory(facts, query, limit, kinds) {
         ...(query.at?.length ? { indexes: facts.contextIndexes(query.at.map(parseRequiredActivityId), query.contextBefore ?? 0, query.contextAfter ?? 0) } : {}),
         kinds: search === undefined ? kinds : ['say', 'done'],
     };
-    let selected, totalMatches, publicBefore, publicAfter;
+    let selected, totalMatches, publicBefore = false, publicAfter = false;
     if (recipient === undefined && search === undefined && limit !== null && limit <= PAGE_SIZE) {
         selected = facts.activityHeads(filter, { edge: afterIndex === undefined ? 'newest' : 'oldest', limit }).items;
-        const publicHeads = selected.filter((head) => ARCHIVE.has(head.kind));
-        const publicFilter = { ...filter, kinds: [...ARCHIVE] };
         totalMatches = facts.activityCount(filter);
-        publicBefore = publicHeads.length > 0 && facts.activityCount({ ...publicFilter, beforeIndex: publicHeads[0].index }) > 0;
-        publicAfter = publicHeads.length > 0 && facts.activityCount({ ...publicFilter, afterIndex: publicHeads.at(-1).index }) > 0;
+        if (presentation) {
+            const publicHeads = selected.filter((head) => ARCHIVE.has(head.kind));
+            const publicFilter = { ...filter, kinds: [...ARCHIVE] };
+            publicBefore = publicHeads.length > 0 && facts.activityCount({ ...publicFilter, beforeIndex: publicHeads[0].index }) > 0;
+            publicAfter = publicHeads.length > 0 && facts.activityCount({ ...publicFilter, afterIndex: publicHeads.at(-1).index }) > 0;
+        }
     }
     else {
         const page = [];
@@ -68,7 +70,7 @@ export function selectHistory(facts, query, limit, kinds) {
                 if (matches !== undefined && !matches.has(head.index))
                     continue;
                 totalMatches++;
-                if (ARCHIVE.has(head.kind)) {
+                if (presentation && ARCHIVE.has(head.kind)) {
                     firstPublic = Math.min(firstPublic, head.index);
                     lastPublic = head.index;
                 }
@@ -82,14 +84,16 @@ export function selectHistory(facts, query, limit, kinds) {
             cursor = source.items.at(-1).index;
         }
         selected = page;
-        const publicHeads = selected.filter((head) => ARCHIVE.has(head.kind));
-        publicBefore = publicHeads.length > 0 && firstPublic < publicHeads[0].index;
-        publicAfter = publicHeads.length > 0 && lastPublic > publicHeads.at(-1).index;
+        if (presentation) {
+            const publicHeads = selected.filter((head) => ARCHIVE.has(head.kind));
+            publicBefore = publicHeads.length > 0 && firstPublic < publicHeads[0].index;
+            publicAfter = publicHeads.length > 0 && lastPublic > publicHeads.at(-1).index;
+        }
     }
     const activities = [...facts.activities(selected.map((head) => head.index))];
     if (query.order === 'desc')
         activities.reverse();
-    const visibleActivities = activities.filter((activity) => ARCHIVE.has(activity.kind));
+    const visibleActivities = presentation ? activities.filter((activity) => ARCHIVE.has(activity.kind)) : [];
     const direction = afterIndex === undefined ? 'before' : 'after';
     const cursor = visibleActivities.length === 0 ? undefined : direction === 'before'
         ? Math.min(...visibleActivities.map((activity) => activity.index)) : Math.max(...visibleActivities.map((activity) => activity.index));
@@ -156,9 +160,9 @@ function classifyPresence(participants, now) {
         classificationByName: Object.fromEntries(participants.map((participant) => [participant.name, participant.state === 'done' ? 'done'
                 : participant.state === 'not joined' ? 'not-joined' : hereNames.has(participant.name) ? 'here' : 'lingering'])) };
 }
-export function queryParticipants(facts, context) {
+export function queryParticipants(facts, context, presentation = true) {
     const participants = coreParticipants(facts, context.now);
-    return { data: { participants }, projection: { ...context, ...classifyPresence(participants, context.now),
+    return { data: { participants }, projection: !presentation ? undefined : { ...context, ...classifyPresence(participants, context.now),
             standingCount: inSquareCount(facts), held: facts.hold().active } };
 }
 export async function listPresentation(square, control) {
@@ -170,30 +174,34 @@ export async function listPresentation(square, control) {
         return { context: facts.header().preamble, participants, activities: facts.activityCount({ kinds: ['say'] }) };
     }, control?.signal)).value;
 }
-export function queryStatus(facts, context, viewer = '') {
-    const { data: { participants }, projection } = queryParticipants(facts, context);
-    const header = facts.header(), hold = facts.hold();
+export function queryStatus(facts, context, viewer = '', presentation = true) {
+    const participants = coreParticipants(facts, context.now);
+    const header = facts.header(), hold = facts.hold(), standingCount = inSquareCount(facts);
     const latest = facts.activityHeads({ kinds: ['say', 'done'] }, { edge: 'newest', limit: 1 }).items[0];
     const latestAct = latest === undefined ? undefined : facts.activity(latest.index);
+    const data = {
+        hardCap: header.hardCap,
+        ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
+        activeCount: standingCount, doneCount: participants.filter((p) => p.state === 'done').length,
+        hold: hold.active ? {
+            ...(hold.actor === undefined ? {} : { by: hold.actor }),
+            ...(hold.reason === undefined ? {} : { reason: hold.reason }),
+            ...(hold.at === undefined ? {} : { at: hold.at }),
+        } : null,
+        participants: participants.filter((p) => p.state !== 'not joined'), now: context.now,
+        ...(latestAct === undefined || latestAct.actor === undefined || latestAct.kind === 'read' ? {} : { latestActivity: toPublicActivity(latestAct) }),
+    };
+    if (!presentation)
+        return { data, projection: undefined };
     const afterIndex = latestAct?.index ?? -1;
     const joins = facts.activities(facts.activityHeads({ kinds: ['join'], afterIndex }, { edge: 'newest', limit: 3 }).items.map((h) => h.index)).map((activity) => ({ activity,
         rejoined: facts.activityCount({ kinds: ['done'], actors: [activity.actor], actorMatch: 'exact', beforeIndex: activity.index }) > 0 }));
     const canonicalViewer = facts.participant(viewer)?.name ?? viewer;
     return {
-        data: {
-            hardCap: header.hardCap,
-            ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
-            activeCount: projection.standingCount, doneCount: participants.filter((p) => p.state === 'done').length,
-            hold: hold.active ? {
-                ...(hold.actor === undefined ? {} : { by: hold.actor }),
-                ...(hold.reason === undefined ? {} : { reason: hold.reason }),
-                ...(hold.at === undefined ? {} : { at: hold.at }),
-            } : null,
-            participants: participants.filter((p) => p.state !== 'not joined'), now: context.now,
-            ...(latestAct === undefined || latestAct.actor === undefined || latestAct.kind === 'read' ? {} : { latestActivity: toPublicActivity(latestAct) }),
-        },
+        data,
         projection: {
-            ...projection, knownParticipantCount: participants.length, viewer: canonicalViewer,
+            ...context, ...classifyPresence(participants, context.now), standingCount, held: hold.active,
+            knownParticipantCount: participants.length, viewer: canonicalViewer,
             ...(canonicalViewer === '' ? {} : { participant: canonicalViewer }),
             joins, joinCount: facts.activityCount({ kinds: ['join'], afterIndex }),
             attentionNames: participants.filter((p) => canonicalViewer === '' || nameKey(p.name) === nameKey(canonicalViewer)).map((p) => p.name),

package/guides/application-demand-optimization.md

@@ -0,0 +1,50 @@
+# Application presentation demand
+
+## Design
+
+`createSquareApplication(context)` retains complete terminal-facing outcomes. MCP uses `createSquareApplication(context, { presentation: false })`; its outcome has the same `data` contract and `projection: undefined`.
+
+This is one explicit result demand, not a second business implementation. The application still owns admission, retries, receipts, cancellation and delivery. Ordinary early returns and conditional expressions skip presentation work where it was previously performed; there is no deferred projector, registry, cache or resource-lifetime change. CLI projection types remain required, while the data-only factory overload exposes their absence explicitly.
+
+MCP no longer requests join history/perceptions, the pre-expression directed feed, catch presence enrichment, listener context reads, lifecycle event rereads, or history/status/participants presentation-only annotations. Selection/counts required for results and history limits remain. For terminal expressions the directed feed is still captured once **before** landing, not after sending or on each retry. Delivery and postcommit publication remain on the original path.
+
+Two same-operation observations are consolidated:
+
+- Catch resolves caller and all sender filters in one typed-fact read, preserving caller-first validation, canonical error subjects, filter order and known-but-departed senders. The actual selection/receipt transaction, ownership admission and lease fences remain separate and current.
+- Expression's known-name check runs inside the existing join preview via an internal `requireKnown` admission option. Unknown names still fail before claiming or mutating; departed participants still reenter once. Ordinary join may still create a name. Preview facts never replace the subsequent ownership/CAS or commit-time checks.
+
+Long-lived MCP connections and concurrent delivery are deliberately outside this change.
+
+## Local MCP measurement
+
+Baseline: `31cc1bf`. Candidate: the presentation-demand and observation changes above. Node v26.10.0. A real MCP client used the SDK's in-memory transport, not a direct call to application helpers. Each call still creates its application and opens/closes the artifact.
+
+Three runs per variant, alternating B1/A1/B2/A2/B3/A3. Each process seeds four participants and 120 2,048-byte historical says outside measurement, joins the probe participant, then runs three warmup cycles and twenty measured cycles of repeated join, express, two empty filtered catches, history and status. Harness session keys are cleared: the probe's `reconnect` label means a repeated no-op join (`kind: joined`), not a real harness ownership reconnect. New measured expressions are small (`probe body`) and use force without pending directed feed; catches are empty. This is not a bulk-payload, ownership-contention or concurrent benchmark. No test suite, build or second benchmark ran alongside the six probes.
+
+Wall times below are the median of three run-level p50s, each from twenty measured calls. Small local timings are illustrative, not a production SLA or the earlier 300-process catch-p95 workload. The stable transaction/statement counts establish removed work more directly.
+
+| MCP operation | Wall p50 before → after (ms) | Artifact read transactions/call | SQL prepares/call |
+| --- | ---: | ---: | ---: |
+| Repeated no-op join | 1.478 → 1.036 | 3 → 2 | 30 → 15 |
+| Express | 3.963 → 3.372 | 6 → 4 | 79 → 61 |
+| Empty catch, one sender filter | 3.157 → 1.613 | 5 → 3 | 124 → 40 |
+| Empty catch, three sender filters | 3.335 → 1.655 | 7 → 3 | 134 → 42 |
+| History | 1.582 → 0.808 | 2 → 2 | 52 → 16 |
+| Status | 2.344 → 2.093 | 2 → 2 | 103 → 94 |
+
+Sender lookups still scale with filter count; **transactions do not**. No participant validation has been omitted to obtain that result. Repeated join's body-hydrating row reads fall from ten to zero per call. History still hydrates its ten result rows, and both empty catches hydrate none. Express and status each retain one body-hydrating row in this probe; not all body reads are presentation work.
+
+SQLite counters are attributed by canonical database location. Host-ledger/lock database work is counted separately, never attributed to the artifact. A positive calibration observes one port read as one artifact read transaction and `activities([0,1])` as two hydrated rows. History moves the same hydration counters used for the zero checks. Hydrated bytes in the probe mean returned string/blob bytes, not filesystem I/O.
+
+All six probes passed their calibration, first-join, hydration and no-error controls: 720 measured calls plus six first joins have no recorded errors. Warmup results are not retained or included in that gate. Raw per-call records retain timing/counters/errors but not complete returned payloads; each operation also retains its first measured result summary. Public-data/error parity is established by regression tests, not by those no-error benchmark controls. Recorded compiled-module hashes were checked before and after each probe; the probe script itself was not included in those historical hash manifests. Independent review recomputed the raw timing/counter statistics and confirmed the stated measurement limits.
+
+## Regression evidence
+
+- New tests prove MCP avoids the extra presentation reads, while terminal-facing join/express still hydrate real presentation content and express retains its pre-send feed.
+- A body-bearing catch hydrates exactly its selected page; empty catch and archive/status/participants data parity remain intact.
+- One versus multiple catch filters has the same read-transaction count; canonical caller/filter errors remain distinct.
+- Both new tests fail against the unchanged baseline at the intended hydration/transaction assertions.
+- The existing CLI/application/MCP activity/receipt parity, never-joined refusal, departed reentry, metadata ownership, cancellation and postcommit behavior tests pass.
+- Full suite: 680 passed, one opt-in Claude runtime test skipped. CLI process suite: 48 passed. Independent static review accepted correctness and control-flow clarity.
+
+Local evidence: `/tmp/square-upper-{before,after}-{1,2,3}.{json,log,exit,sha,integrity}`. Probe: `/tmp/square-mcp-demand-bench.mjs`. Test logs: `/tmp/square-upper-{tests,cli,negative}.log`.

package/guides/catch-cold-path-optimization.md

@@ -0,0 +1,56 @@
+# Catch cold-path optimization
+
+## Result and scope
+
+Under the existing 300-process Pi-session workload, first-catch API p95 falls by **60.4% / 61.4%** for histories of 1,800 / 18,000 activities. These are reductions between the medians of three run-level p95s, not a guarantee for every run or operation. Whole catch-phase p95 falls by about **56%** for both histories.
+
+The comparison is against `90752ba`, the current production implementation plus the same instrumentation, not an older, slower implementation. The benchmark represents Pi sessions without a Paseo route; it does not establish equal gains for Codex/Paseo sessions, emoji-only names, or native notification delivery.
+
+## Two changes
+
+- `model.ts`: try the existing Unicode text-name grammar before the full RGI emoji grammar. It accepts letters, numbers, marks excluding variation selectors, hyphens, underscores, and nonempty slash-separated segments. It is an exact subset of the original grammar; the original full matcher remains the fallback. `NAME_GRAPHEME_SOURCE`, also used by mention scanning, retains its original value.
+- `participant-host.ts`: before discovering installed adapters, use the existing route resolver to check whether any candidate exists. No host ledger or no possible candidate means no route, without importing adapters that cannot be used. Real candidates still pass through the real capability check. Paseo precedence, Codex fallback, harness identity, and publication failure isolation remain unchanged.
+
+CPU sampling of the baseline pointed to cold name validation inside reader transactions and optional adapter module loading during catch. The changes remove that work rather than prewarm it or move it outside measurement. The sampling and this combined experiment do not establish each change's individual contribution.
+
+SQLite storage, DELETE journaling, FULL synchronous durability, transaction validation, ownership/epoch fences, receipts, and retry policy are unchanged. Earlier lock/backoff/cache experiments did not show the required improvement and are not included. The earlier [COMMIT-gap investigation](catch-lock-investigation.md) measured preparation inside writers; it did not bound costs inside concurrent readers or optional postcommit module loading.
+
+## Controlled comparison
+
+```sh
+node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 300 --mode session --active --no-hints
+```
+
+Node v26.10.0. Three runs of each variant, ordered B1, A1, B2, A2, B3, A3. Each command covers both histories. Baseline worktree: `/tmp/square-half-baseline-final`, detached at `90752ba`; candidate: the main worktree with the two changes above. Benchmark scripts were byte-identical. The changed compiled modules and benchmark script were hashed before and checked after every command. No other benchmark, test suite, build, or profile ran alongside the sequence; read-only review and test-source editing did occur. This is a local, alternating experiment, not a randomized or controlled-host latency guarantee.
+
+The benchmark workload is unchanged: 300 processes, 2,048-byte historical bodies, a five-second idle window, bell discovery without filesystem hints, then open, recognize, first catch, empty catch, and close. First-catch timing covers the complete participant catch API. Whole-phase timing includes all those catch-phase steps; it is not one catch call.
+
+### Median of three run-level measurements
+
+| Metric | Before, 1,800 | After, 1,800 | Reduction | Before, 18,000 | After, 18,000 | Reduction |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| First catch API p95 (ms) | 3,923.86 | 1,554.02 | 60.4% | 3,568.86 | 1,378.74 | 61.4% |
+| Whole catch phase p95 (ms) | 4,354.45 | 1,924.30 | 55.8% | 3,907.48 | 1,723.48 | 55.9% |
+| Empty catch API p95 (ms) | 58.49 | 56.60 | 3.2% | 82.22 | 54.84 | 33.3% |
+| Aggregate catch-phase CPU (ms) | 15,643.35 | 7,184.01 | 54.1% | 15,274.12 | 6,515.09 | 57.3% |
+
+### Individual first-catch p95s
+
+| History | Before B1 / B2 / B3 (ms) | After A1 / A2 / A3 (ms) |
+| --- | --- | --- |
+| 1,800 | 4,044.22 / 3,404.54 / 3,923.86 | 1,544.62 / 1,554.02 / 1,720.00 |
+| 18,000 | 3,024.11 / 3,568.86 / 3,759.82 | 1,343.00 / 1,824.53 / 1,378.74 |
+
+The second large-history pair improves by 48.9%, so the evidence does **not** say every paired run exceeded 50%. Both median reductions exceed 50%, and every candidate first-catch p95 is below every baseline p95 in its history group.
+
+## Correctness evidence
+
+All six commands exited successfully with empty stderr. Each of the twelve scenarios had 300 ready/completed workers and discovered all 300 participants. The raw per-worker reports were separately checked, including `remaining` (which the benchmark's built-in success gate does not assert): every worker consumed exactly one activity, had zero remaining, and consumed nothing again. That is 3,600 successful worker outcomes.
+
+Every scenario retained 300 hydrated bodies, 600 SQL writes, 300 committed artifact writes and 1,800 committed artifact reads. The recorded COMMIT execution-plus-gap invariant held. No workload or instrumentation was removed to obtain the reduction.
+
+Focused regression coverage preserves explicit expected acceptance/rejection for Unicode text, complete emoji, slash boundaries, selectors, joiners and malformed strings. A fresh-process module-loading test verifies that no-candidate drafting imports neither adapter, and that real Codex and Pi-plus-Paseo candidates still resolve through installed adapters.
+
+`npm test` passed (678 passed, one opt-in runtime test skipped); the CLI process suite passed all 48 tests. Running the new module-loading test against the unchanged baseline fails at its zero-import assertion (two adapters loaded), providing a negative control. Rebuilding for regression tests preserved the measured production module hashes. An independent review recomputed p95s from raw worker timings and verified the reported medians and outcomes.
+
+Local raw evidence: `/tmp/square-half-final-{before,after}-{1,2,3}.{json,err,exit,sha,integrity}`. Summary and per-worker assertion audit: `/tmp/square-half-final-summary.{py,json}`. The earlier pilot is excluded from the table.

package/guides/catch-lock-investigation.md

@@ -0,0 +1,81 @@
+# Catch lock investigation: preparation, COMMIT retries, and WAL
+
+## Question and finding
+
+Follow-up: [catch cold-path optimization](catch-cold-path-optimization.md) removes unnecessary name-validation and adapter-loading work without adopting WAL; its separate repeated comparison meets the 50% first-catch p95 target.
+
+Does SQL compilation explain the multi-second queue under 300 processes, or is the critical path mainly lock occupancy?
+
+For the current DELETE-journal implementation, preparation inside committed write transactions accounts for about 6% of their cumulative hold-plus-commit time. About 84% of COMMIT wall time occurs **between** synchronous COMMIT calls following BUSY, not inside SQLite calls. Compilation is not the leading measured direct contributor to writer occupancy.
+
+An isolated WAL + FULL experiment removes observed COMMIT BUSY and retry gaps, but does not remove the overall latency problem. Pre-COMMIT hold time increases, ranges overlap, and one large-history WAL run regresses. Do not ship a journal-mode change on this evidence alone.
+
+## Measurement boundaries
+
+`scripts/benchmark-idle-wait.mjs` now records, per connection/origin and transaction mode:
+
+- `holdPrepareMs`: synchronous prepare-call wall time after successful BEGIN and before the first COMMIT attempt, including failed prepares.
+- `commitExecMs`: synchronous COMMIT-call wall time, divided into successful, BUSY, and other-error calls.
+- `commitGapMs`: time between the end of a COMMIT call and the start of its next attempt.
+- `commitMs = commitExecMs + commitGapMs`, within rounding.
+
+Only committed transactions contribute samples; rollback discards the transaction sample. Global prepare counters separately retain all attempts. The synchronous measurements include off-CPU time and wrapper overhead; they are **not CPU or fsync measurements**. Retry gaps include timers, scheduling, and caller work. These measurements cannot distinguish how long readers remain active from how long the writer waits to be scheduled again. A preparation share is not an upper bound on all indirect benefits of reducing preparation in concurrent readers.
+
+In DELETE mode, a writer holding a RESERVED lock needs existing readers to release SHARED locks before it can obtain EXCLUSIVE for commit. BUSY establishes contention; the split establishes where elapsed time occurs. It does not establish that disk synchronization itself costs the full COMMIT wall time. See [SQLite locking](https://www.sqlite.org/lockingv3.html).
+
+## Controlled experiment
+
+Production storage code is `a1bd798`; the concurrent UI-only commit `446e204` does not change this path. The temporary detached worktree `/tmp/square-wal-investigation` has exactly two production-line changes: new artifact creation requests WAL, and the row validator expects WAL. The host ledger remains DELETE. Both variants retain FULL synchronous writes and the same writer retry policy. This experiment supports **fresh artifacts only**, not migration of existing artifacts.
+
+A disposable positive control confirmed WAL, synchronous=2 (FULL), wal_autocheckpoint=1000, and real `-wal`/`-shm` files. Benchmark scripts were byte-identical in both locations; production module hashes on the baseline matched before and after measurement.
+
+```sh
+node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 300 --mode session --active --no-hints
+```
+
+Three runs per variant, each covering histories of 1,800 and 18,000 activities. Execution order was D1, W1, D2, W2, D3, W3; no second benchmark or test suite ran alongside them. An initial raw-report audit ran during D2, so this was not a completely quiescent host. The order is alternating, not randomized; three local runs do not give a general latency guarantee. Both variants used the new instrumentation, so do not compare their absolute timings directly with previous instrumentation's reports.
+
+## Results
+
+Each cell is the median of three run-level measurements. Writer timings below are cumulative across 300 committed write transactions, **not p95s**. Parent and child fields overlap; independently calculated medians need not add up.
+
+| Metric | DELETE, 1,800 | WAL, 1,800 | DELETE, 18,000 | WAL, 18,000 |
+| --- | ---: | ---: | ---: | ---: |
+| First catch API p95 (ms) | 3,287.06 | 2,959.93 | 3,626.62 | 3,162.81 |
+| Empty catch API p95 (ms) | 85.71 | 33.84 | 83.40 | 28.47 |
+| Whole catch phase p95 (ms) | 3,797.29 | 3,255.36 | 4,104.10 | 3,513.85 |
+| Writer hold before COMMIT, total (ms) | 2,137.47 | 2,483.41 | 1,556.86 | 2,872.93 |
+| Preparation within writer hold, total (ms) | 215.62 | 589.84 | 218.35 | 276.82 |
+| Writer COMMIT wall, total (ms) | 1,340.74 | 70.33 | 2,224.91 | 710.17 |
+| Writer synchronous COMMIT calls, total (ms) | 204.95 | 70.33 | 305.45 | 710.17 |
+| Writer inter-COMMIT gaps, total (ms) | 1,166.90 | 0 | 1,881.57 | 0 |
+| Artifact COMMIT BUSY observations | 290 | 0 | 276 | 0 |
+| Aggregate catch-phase CPU (ms) | 15,107.57 | 13,469.20 | 15,766.89 | 13,891.08 |
+
+For DELETE, calculate shares within each run before taking their median:
+
+- Held prepare / (hold + COMMIT): **6.49% / 6.26%** for small/large histories.
+- Inter-call gap / COMMIT wall: **84.07% / 84.57%**.
+
+WAL first-catch p95 medians are about 10% and 13% lower, but individual runs matter:
+
+| History | DELETE first-catch p95 runs (ms) | WAL first-catch p95 runs (ms) |
+| --- | --- | --- |
+| 1,800 | 3,052.04 / 3,788.98 / 3,287.06 | 2,959.93 / 3,560.27 / 2,272.82 |
+| 18,000 | 3,626.62 / 3,449.42 / 4,044.86 | 3,162.81 / **4,963.89** / 2,626.30 |
+
+WAL removes the measured BUSY-commit mechanism but changes I/O, checkpointing, and reader concurrency too. The larger pre-COMMIT hold and variability are observations, not proof of any one scheduling cause. The second large-history WAL run is slower than every DELETE run. These results do not justify a claim of stable overall acceleration.
+
+All twelve scenarios discovered 300 participants, consumed exactly one activity per participant, and consumed none again: 3,600 successful worker outcomes. Each scenario retained 300 hydrated bodies, 600 SQL writes, 300 committed artifact writes and 1,800 committed artifact reads. All six commands exited successfully with empty stderr. The expanded bounded instrumentation self-test passed, including real busy COMMIT splitting, failed preparation, origin separation, and rollback/reset.
+
+Raw reports: `/tmp/square-journal-{delete,wal}-{1,2,3}.{json,err,exit}`. Local summary: `/tmp/square-journal-summary.mjs`. The temporary WAL changes are **not** in production.
+
+## What remains before any WAL adoption
+
+- Existing DELETE V2 artifacts and old readers need an explicit compatibility/migration decision; the experimental validator simply refuses them.
+- WAL contains committed state until checkpointed. Backup/move/recovery, alias paths and directory permissions must account for it. Standard WAL requires processes on the same host.
+- Observe long readers, WAL size, checkpoint timing and recovery. This short benchmark does not measure long-lived WAL growth or a final last-connection checkpoint; its parent artifact connection remains open. `artifactBytes` counts only the main file, not sidecars.
+- `list.ts` uses main-file mtime for `lastActiveAt`; WAL commits need not update it. The existing file watcher does recognize `-wal`, but a `--no-hints` benchmark does not validate native notifications.
+- Retain FULL durability. WAL + NORMAL would change power-loss guarantees and is not an equivalent performance comparison.
+
+See [SQLite WAL](https://www.sqlite.org/wal.html) for concurrency, checkpointing, durability and operational tradeoffs. Next investigation should target why read transactions and scheduling prolong the retry gaps, or reduce redundant transaction/validation work, rather than assume compilation or a journal-mode toggle alone resolves the queue.

package/guides/host-ledger.md

@@ -22,7 +22,7 @@ Verification is read-only. It checks SQLite identity, version, schema, integrity
 
 To upgrade an NDJSON ledger:
 
-1. Stop **every** Square host using that ledger, including interactive harnesses and background agents. Do not run old and new hosts together.
+1. Stop **every** agent session and MCP service using Square with this ledger, including interactive harnesses and background agents. Do not run old and new ones together.
 2. Keep a backup of the stopped legacy files.
 3. Run:
 
@@ -36,7 +36,7 @@ To upgrade an NDJSON ledger:
 
 Migration does not stop or restart hosts. Its locks fence compatible writers but do not prove hosts are stopped. It acquires the ownership claim fence, then `presence.ndjsonl.lock`, then `evidence.ndjsonl.lock`.
 
-An older SQLite ledger format is upgraded in place by the same `square ledger migrate` under the same stopped-hosts prerequisite and the same lock order. The upgrade preserves every record, duplicate, original order and both observer revisions. `square ledger verify` stays read-only: it refuses an older or unsupported database with the migrate command and never upgrades silently.
+An older SQLite ledger format is upgraded in place by the same `square ledger migrate` under the same stopped-sessions prerequisite and the same lock order. The upgrade preserves every record, duplicate, original order and both observer revisions. `square ledger verify` stays read-only: it reports a supported old format with the migrate command and never upgrades silently. An unsupported format version or an unrelated database is refused with a diagnosis path instead: migration is not a repair command, and a failed migration is never answered by rerunning it blindly.
 
 The importer preserves all ages, future records, duplicates, original order, native correlation and residual fields. It ignores malformed JSON, wrong versions and records without a numeric timestamp, as the old reader did, and reports those counts. Any valid version-1 record whose indexed fields are unsafe refuses the entire conversion rather than losing evidence. Refusal identifies only source kind, rejected count and first rejected line; no accepted subset is published. Legacy unknown wake sources are normalized once during import.
 

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.73",
+  "version": "0.3.75",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
@@ -77,6 +77,7 @@
     ]
   },
   "dependencies": {
+    "@earendil-works/pi-tui": "^1.3.0",
     "@modelcontextprotocol/sdk": "^1.32.0",
     "cross-spawn": "^7.0.6",
     "zod": "^4.6.5"

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

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

package/plugins/claude/skills/square/SKILL.md

@@ -65,7 +65,7 @@ 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. 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.
+**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. An unmatched `@name` stays ordinary body text and never blocks landing; only standing matches become recipients. 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`, `--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.
 

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

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

package/plugins/paseo/README.md

@@ -26,13 +26,18 @@ plain-text detail are projected into a card. Real tools, other custom messages,
 and unrecognized rows remain unchanged.
 
 The collapsed heading uses `metadata.details.items`; it never reverse-parses
-the content. Expansion shows `detail.text` verbatim, including fences, clipping
-notices, and catch commands. Copy content copies that exact string. It does not
-fetch extra activity or mark anything seen. Live events and fetched history use
+the content. Expansion shows `metadata.details.fullText` when available: complete
+notification bodies, even when the model preview was clipped or omitted. Older
+messages fall back to `detail.text`, including clipping notices and catch commands.
+Long content scrolls inside a bounded panel. The
+card does not fetch extra activity or mark anything seen. Live events and fetched history use
 the same transformer.
 
-The card uses Paseo theme colors, selectable text, accessible expansion state,
-and compact layout on narrow displays. Removing the plugin restores Paseo's
+The card is visually marked as Square: an accent glyph, a SQUARE badge, and the
+square's name sit above the actor line, on a raised surface distinct from ordinary
+tool output. It uses Paseo theme colors, selectable text, accessible expansion state,
+and compact layout on narrow displays. Expansion starts at the top-right arrow;
+collapse returns from the arrow below the expanded content. Removing the plugin restores Paseo's
 ordinary custom-message row.
 
 ## Develop