@astrosheep/square 0.3.54 → 0.3.56

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

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.54",
+  "version": "0.3.56",
   "description": "Native Claude Code turn-boundary delivery for Square participants",
   "author": {
     "name": "Square"

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

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

package/dist/attention-presentation.js

@@ -25,10 +25,13 @@ export function renderAttentionPreview(attention) {
         to: attention.recipient,
         kind: attentionKind,
     };
+    const entries = Object.entries(attributes);
+    const [lastKey, lastValue] = entries[entries.length - 1];
     return [
         '<square-activity',
-        ...Object.entries(attributes).map(([key, value]) => `  ${key}="${escapeAttribute(value)}"`),
-        '>',
+        // The opening tag must never emit a standalone `>` line: Markdown renders it as a blockquote.
+        ...entries.slice(0, -1).map(([key, value]) => `  ${key}="${escapeAttribute(value)}"`),
+        `  ${lastKey}="${escapeAttribute(lastValue)}">`,
         previewAttentionBody(attention.body),
         '</square-activity>',
         ...(attentionBodyIsClipped(attention.body)

package/dist/boundary-presentation.d.ts

@@ -3,4 +3,4 @@ import type { InboxMembership } from './model.js';
 export declare function pendingAtBoundary(inbox: InboxMembership[]): InboxMembership[];
 export declare function renderPendingAtBoundary(inbox: InboxMembership[]): string;
 /** Serialize a boundary across hook processes so one stale inbox cannot render twice. */
-export declare function presentPendingAtBoundary<T>(sessionId: string, present: (context: string) => T | Promise<T>, lookup?: (sessionId: string, env?: NodeJS.ProcessEnv) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<T | undefined>;
+export declare function presentPendingAtBoundary<T>(sessionId: string, present: (context: string) => T | Promise<T>, lookup?: (sessionId: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<T | undefined>;

package/dist/boundary-presentation.js

@@ -12,6 +12,29 @@ import { presentationSuppressesWake, projectPresentationEvidence } from './squar
 import { formatActivityId } from './square-core.js';
 const CONTEXT_MAX = 1200;
 const presentationLocks = new Map();
+/** One settled promise loses to an abort so an in-process presentation wait stays bounded too. */
+async function awaitWithSignal(promise, signal) {
+    if (signal === undefined)
+        return promise;
+    let onAbort;
+    try {
+        await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                if (signal.aborted) {
+                    reject(signal.reason ?? new Error('Presentation aborted'));
+                    return;
+                }
+                onAbort = () => reject(signal.reason ?? new Error('Presentation aborted'));
+                signal.addEventListener('abort', onAbort, { once: true });
+            }),
+        ]);
+    }
+    finally {
+        if (onAbort !== undefined)
+            signal.removeEventListener('abort', onAbort);
+    }
+}
 function pendingCount(inbox) {
     return inbox.reduce((total, membership) => total + membership.notifications.length, 0);
 }
@@ -71,7 +94,7 @@ function renderBoundary(inbox) {
     };
 }
 async function presentPendingAtBoundaryUnlocked(sessionId, present, lookup = sessionInbox, env = process.env, signal) {
-    const inbox = await lookup(sessionId, env);
+    const inbox = await lookup(sessionId, env, signal);
     if (signal?.aborted)
         return undefined;
     const hostLedger = hostLedgerForEnv(env);
@@ -97,7 +120,7 @@ async function presentPendingAtBoundaryUnlocked(sessionId, present, lookup = ses
         let square;
         try {
             try {
-                square = await openSquare(entry.membership.squarePath, { env });
+                square = await openSquare(entry.membership.squarePath, { env, signal });
             }
             catch {
                 continue;
@@ -106,16 +129,18 @@ async function presentPendingAtBoundaryUnlocked(sessionId, present, lookup = ses
                 const key = `${entry.membership.squarePath}\u0000${entry.membership.name.toLocaleLowerCase()}\u0000${index}`;
                 const prior = presentationLocks.get(key);
                 if (prior !== undefined) {
-                    await prior;
+                    await awaitWithSignal(prior, signal);
+                    if (signal?.aborted)
+                        return undefined;
                     if (!rendered)
                         return undefined;
                     continue;
                 }
-                const work = presentPending({ artifact: square.artifact, location: entry.membership.squarePath, participant: entry.membership.name, activity: index, hostLedger: square.hostLedger, session: sessionId, sink: { present: renderOnce }, markSeen: entry.markSeen, now: Date.now() }).then(async (outcome) => {
+                const work = presentPending({ artifact: square.artifact, location: entry.membership.squarePath, participant: entry.membership.name, activity: index, hostLedger: square.hostLedger, session: sessionId, sink: { present: renderOnce }, markSeen: entry.markSeen, now: Date.now(), signal }).then(async (outcome) => {
                     // A stale projection can outlive its activity; still surface the bounded preview,
                     // but there is no artifact observation to commit.
                     if (!outcome.presented) {
-                        const snapshot = await square.artifact.read().catch(() => undefined);
+                        const snapshot = await square.artifact.read(signal).catch(() => undefined);
                         if (snapshot?.state.acts.every((activity) => activity.index !== index))
                             await renderOnce();
                     }

package/dist/codex-hook.d.ts

@@ -6,6 +6,10 @@ export interface CodexHookInput {
     cwd?: unknown;
     source?: unknown;
 }
-export declare function codexHookResponse(input: CodexHookInput, lookup?: (sessionId: string, env?: NodeJS.ProcessEnv) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv, deliveryAdapters?: WakeAdapter[]): Promise<object | undefined>;
+export type HookTrace = (line: string) => void;
+/** Overall hook budget: Codex kills the hook at its configured 5s timeout, so the hook must
+ * bound every wait/retry itself and exit with a readable stage trace before that. */
+export declare const CODEX_HOOK_BUDGET_MS = 4500;
+export declare function codexHookResponse(input: CodexHookInput, lookup?: (sessionId: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv, deliveryAdapters?: WakeAdapter[], trace?: HookTrace): Promise<object | undefined>;
 export declare function runCodexHook(inputText: string, env?: NodeJS.ProcessEnv): Promise<string>;
 export declare function runCodexHookAsync(inputText: string, env?: NodeJS.ProcessEnv): Promise<string>;

package/dist/codex-hook.js

@@ -3,12 +3,30 @@ import { sessionInbox } from './inbox.js';
 import { automaticSessionEnd, automaticSessionStart } from './automatic-session.js';
 import { clearCodexBoundary, recordCodexBoundary } from './codex-boundary-state.js';
 import { PRIVILEGED_HOOK_BUDGET_MS, sweepPrivilegedPending } from './notifications.js';
+/** Overall hook budget: Codex kills the hook at its configured 5s timeout, so the hook must
+ * bound every wait/retry itself and exit with a readable stage trace before that. */
+export const CODEX_HOOK_BUDGET_MS = 4500;
 const CODEX_HOOK_EVENTS = {
     PostToolUse: 'PostToolUse',
     Stop: 'Stop',
 };
-export async function codexHookResponse(input, lookup = sessionInbox, env = process.env, deliveryAdapters) {
-    const sweepDeadline = Date.now() + PRIVILEGED_HOOK_BUDGET_MS;
+const defaultTrace = (line) => { process.stderr.write(`${line}\n`); };
+/** Per-stage timings, emitted as each stage completes so a killed hook still leaves a trace. */
+function stageTracer(trace) {
+    const startedAt = Date.now();
+    let mark = startedAt;
+    return (stage, extra = '') => {
+        const now = Date.now();
+        const durationMs = now - mark;
+        mark = now;
+        trace(`square-codex-hook: stage=${stage} durationMs=${durationMs} totalMs=${now - startedAt}${extra === '' ? '' : ` ${extra}`}`);
+    };
+}
+function hookBudgetMs(env) {
+    const configured = Number(env.SQUARE_CODEX_HOOK_BUDGET_MS ?? CODEX_HOOK_BUDGET_MS);
+    return Number.isFinite(configured) && configured > 0 ? configured : CODEX_HOOK_BUDGET_MS;
+}
+export async function codexHookResponse(input, lookup = sessionInbox, env = process.env, deliveryAdapters, trace = defaultTrace) {
     if (typeof input.session_id !== 'string' || input.session_id === '')
         return undefined;
     if (typeof input.hook_event_name !== 'string')
@@ -16,13 +34,28 @@ export async function codexHookResponse(input, lookup = sessionInbox, env = proc
     const hookEventName = CODEX_HOOK_EVENTS[input.hook_event_name];
     if (hookEventName === undefined)
         return undefined;
+    const stage = stageTracer(trace);
+    const signal = AbortSignal.timeout(hookBudgetMs(env));
+    const sweepDeadline = Date.now() + Math.min(PRIVILEGED_HOOK_BUDGET_MS, hookBudgetMs(env));
+    const cwd = typeof input.cwd === 'string' ? input.cwd : process.cwd();
     await recordCodexBoundary(input.session_id, hookEventName === 'Stop' ? 'Stop' : 'non-stop', env);
+    stage('boundary-record');
     if (hookEventName === 'Stop') {
-        await sweepPrivilegedPending(typeof input.cwd === 'string' ? input.cwd : process.cwd(), env, deliveryAdapters, sweepDeadline).catch(() => undefined);
+        await sweepPrivilegedPending(cwd, env, deliveryAdapters, sweepDeadline, signal).catch(() => undefined);
+        stage('sweep', signal.aborted ? 'aborted=true' : '');
         return undefined;
     }
-    const response = await presentPendingAtBoundary(input.session_id, (context) => ({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: context } }), lookup, env);
-    await sweepPrivilegedPending(typeof input.cwd === 'string' ? input.cwd : process.cwd(), env, deliveryAdapters, sweepDeadline).catch(() => undefined);
+    let response;
+    try {
+        response = await presentPendingAtBoundary(input.session_id, (context) => ({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: context } }), lookup, env, signal);
+        stage('presentation', signal.aborted ? 'aborted=true' : '');
+    }
+    catch (error) {
+        stage('presentation', `error=${error instanceof Error ? error.name : String(error)}`);
+        response = undefined;
+    }
+    await sweepPrivilegedPending(cwd, env, deliveryAdapters, sweepDeadline, signal).catch(() => undefined);
+    stage('sweep', signal.aborted ? 'aborted=true' : '');
     return response;
 }
 export async function runCodexHook(inputText, env = process.env) {

package/dist/inbox.d.ts

@@ -9,6 +9,6 @@ export interface PendingWaitOptions {
     /** Reports whether a change wait has been established for a deferred retry. */
     onChangeArmed?: (armed: boolean) => void;
 }
-export declare function sessionInbox(sessionId: string, env?: NodeJS.ProcessEnv): Promise<InboxMembership[]>;
+export declare function sessionInbox(sessionId: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<InboxMembership[]>;
 /** Wait for a bound square to produce a new pending notification without consuming it. */
 export declare function waitForSessionPending(sessionId: string, timeoutMs: number, options?: PendingWaitOptions, env?: NodeJS.ProcessEnv): Promise<InboxMembership[]>;

package/dist/inbox.js

@@ -24,13 +24,13 @@ function withoutExcluded(inbox, excludeKeys) {
     }))
         .filter((membership) => membership.notifications.length > 0);
 }
-export async function sessionInbox(sessionId, env = process.env) {
+export async function sessionInbox(sessionId, env = process.env, signal) {
     const inbox = [];
     const hostLedger = hostLedgerForEnv(env);
     for (const binding of await projectSessionBindings({ hostLedger, sessionId })) {
         let square;
         try {
-            square = await openSquare(binding.location, { env, hostLedger });
+            square = await openSquare(binding.location, { env, hostLedger, signal });
             const projection = await projectPresentation({ artifact: square.artifact, binding, now: square.clock() });
             if (!projection.joined)
                 continue;

package/dist/notifications.d.ts

@@ -23,7 +23,7 @@ export declare function createDefaultWakeTransport(hostLedger: import('./host-le
 export declare function createWakeTransport(adapters: readonly WakeAdapter[], hostLedger: import('./host-ledger.js').HostLedgerPort, clock: () => number): WakeTransportPort;
 export declare function processActNotificationsOnce(squarePath: string, actIndex: number, opts?: ProcessNotificationOptions): Promise<import("./ports.js").DeliveryResult>;
 /** Privileged hook fallback: sweep indexed squares plus the current cwd's local squares within one boundary budget. */
-export declare function sweepPrivilegedPending(cwd: string, env?: NodeJS.ProcessEnv, suppliedAdapters?: WakeAdapter[], deadline?: number): Promise<void>;
+export declare function sweepPrivilegedPending(cwd: string, env?: NodeJS.ProcessEnv, suppliedAdapters?: WakeAdapter[], deadline?: number, signal?: AbortSignal): Promise<void>;
 export interface SweepPendingNotificationsOptions {
     env?: NodeJS.ProcessEnv;
     now?: number;

package/dist/notifications.js

@@ -192,9 +192,9 @@ export async function processActNotificationsOnce(squarePath, actIndex, opts = {
     }
 }
 /** Privileged hook fallback: sweep indexed squares plus the current cwd's local squares within one boundary budget. */
-export async function sweepPrivilegedPending(cwd, env = process.env, suppliedAdapters, deadline = Date.now() + PRIVILEGED_HOOK_BUDGET_MS) {
+export async function sweepPrivilegedPending(cwd, env = process.env, suppliedAdapters, deadline = Date.now() + PRIVILEGED_HOOK_BUDGET_MS, signal) {
     const remainingMs = () => Math.max(0, deadline - Date.now());
-    if (remainingMs() === 0)
+    if (remainingMs() === 0 || signal?.aborted)
         return;
     const root = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
     const hostLedger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? root, localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? root, readableScopes: ['user'], writableScope: 'user' });
@@ -211,17 +211,17 @@ export async function sweepPrivilegedPending(cwd, env = process.env, suppliedAda
         }
     }
     catch { /* no local square directory */ }
-    if (remainingMs() === 0)
+    if (remainingMs() === 0 || signal?.aborted)
         return;
     const adapters = suppliedAdapters ?? await defaultWakeAdapters();
     for (const squarePath of paths) {
-        if (remainingMs() === 0)
+        if (remainingMs() === 0 || signal?.aborted)
             break;
         try {
-            const square = await openSquare(squarePath, { hostLedger, env });
+            const square = await openSquare(squarePath, { hostLedger, env, signal });
             try {
                 await hostLedger.reconcileBinding({ artifact: square.artifact, scopes: ['user'], now: Date.now() }).catch(() => undefined);
-                if (remainingMs() === 0)
+                if (remainingMs() === 0 || signal?.aborted)
                     break;
                 const limit = Number.parseInt(env.SQUARE_NOTIFY_SWEEP_LIMIT ?? '8', 10);
                 const graceMs = 0;
@@ -229,7 +229,7 @@ export async function sweepPrivilegedPending(cwd, env = process.env, suppliedAda
                 const transport = createWakeTransport(adapters, hostLedger, Date.now);
                 for (const actIndex of selected) {
                     const remaining = remainingMs();
-                    if (remaining === 0)
+                    if (remaining === 0 || signal?.aborted)
                         break;
                     const configured = Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000);
                     const timeoutMs = Math.max(1, Math.min(Number.isFinite(configured) && configured > 0 ? configured : 5000, remaining));

package/dist/ports.d.ts

@@ -4,14 +4,14 @@ export type { ClaimResult, EvidenceClaim, EvidenceRelease, EvidenceGc, EvidenceL
 import type { HostLedgerPort } from './host-ledger.js';
 /** Atomic artifact access. Never exposes framing, compression, locks, or storage schema. */
 export interface SquareArtifactPort {
-    read(): Promise<{
+    read(signal?: AbortSignal): Promise<{
         state: SquareState;
         version: number;
     }>;
     transact<R>(fn: (state: SquareState, version: number) => {
         state?: SquareState;
         result: R;
-    }): Promise<R>;
+    }, signal?: AbortSignal): Promise<R>;
     changed(sinceVersion: number, timeoutMs: number): Promise<boolean>;
     close(): Promise<void>;
 }
@@ -134,6 +134,8 @@ export interface PresentPendingInput {
     readonly session?: string;
     readonly now?: number;
     readonly timeoutMs?: number;
+    /** One hook deadline propagated into artifact reads/transitions so busy retries stay bounded. */
+    readonly signal?: AbortSignal;
     /** Boundary previews that were clipped remain pending for a later full presentation. */
     readonly markSeen?: boolean;
 }

package/dist/presentation-operations.js

@@ -8,7 +8,7 @@ export async function presentPending(input) {
         return { presented: false };
     let before;
     try {
-        before = await input.artifact.read();
+        before = await input.artifact.read(input.signal);
     }
     catch {
         return { presented: false };
@@ -25,7 +25,7 @@ export async function presentPending(input) {
         claimToken = claim.claimToken;
         let current;
         try {
-            current = await input.artifact.read();
+            current = await input.artifact.read(input.signal);
         }
         catch {
             await input.hostLedger.releaseEvidence({ location: input.location, participant: input.participant, session: input.session, activity: formatActivityId(index), kind: 'presentation', claimToken }).catch(() => undefined);
@@ -46,7 +46,7 @@ export async function presentPending(input) {
     else
         await input.sink.present(item);
     if (input.markSeen !== false)
-        await input.artifact.transact((state) => { const changed = recordObservation(state, input.participant, index, 'seen', input.now ?? Date.now()); return changed ? { state, result: undefined } : { result: undefined }; });
+        await input.artifact.transact((state) => { const changed = recordObservation(state, input.participant, index, 'seen', input.now ?? Date.now()); return changed ? { state, result: undefined } : { result: undefined }; }, input.signal);
     if (input.hostLedger !== undefined && input.session !== undefined && claimToken !== undefined)
         await input.hostLedger.appendEvidence({ location: input.location, participant: input.participant, session: input.session, activity: formatActivityId(index), kind: 'presentation', outcome: input.markSeen === false ? 'clipped' : 'presented', ...(input.markSeen === false ? { message: 'presentation clipped' } : {}), claimToken });
     return { presented: true, activity: item };

package/dist/square-file-adapter.d.ts

@@ -13,8 +13,10 @@ export interface SquareBuildOptions {
     hostLedger?: HostLedgerPort;
     wakeTransport?: import('./ports.js').WakeTransportPort;
     env?: NodeJS.ProcessEnv;
+    /** One caller deadline (e.g. a native hook budget) propagated into artifact busy retries. */
+    signal?: AbortSignal;
 }
-export declare function openSquare(squarePath: string, options?: Pick<SquareBuildOptions, 'clock' | 'hostLedger' | 'wakeTransport' | 'env'>): Promise<OpenSquare>;
+export declare function openSquare(squarePath: string, options?: Pick<SquareBuildOptions, 'clock' | 'hostLedger' | 'wakeTransport' | 'env' | 'signal'>): Promise<OpenSquare>;
 export declare function probeSquare(squarePath: string): Promise<OpenSquare | undefined>;
 export declare function buildSquare(squarePath: string, options: SquareBuildOptions): Promise<OpenSquare>;
 export declare function buildMemorySquare(options: SquareBuildOptions): OpenSquare;

package/dist/square-file-adapter.js

@@ -27,10 +27,10 @@ function validateBuildOptions(options) {
 export async function openSquare(squarePath, options = {}) {
     const env = options.env ?? process.env;
     const ledgerRoot = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
-    const cell = openSquareCell(squarePath);
+    const cell = openSquareCell(squarePath, options.signal);
     try {
         await cell.read();
-        const artifact = { read: () => cell.read(), transact: (fn) => cell.transact(fn), changed: (since, timeout) => cell.changed(since, timeout), close: () => cell.close() };
+        const artifact = { read: (signal) => cell.read(signal), transact: (fn, signal) => cell.transact(fn, signal), changed: (since, timeout) => cell.changed(since, timeout), close: () => cell.close() };
         return {
             artifact,
             clock: options.clock ?? Date.now,
@@ -82,7 +82,7 @@ export function buildMemorySquare(options) {
     return { artifact: memoryArtifact(createMemoryCell(squareState)), clock: options.clock ?? Date.now, location: 'memory', hostLedger: options.hostLedger, wakeTransport: options.wakeTransport };
 }
 function memoryArtifact(cell) {
-    return { read: () => cell.read(), transact: (fn) => cell.transact(fn), changed: (since, timeout) => cell.changed(since, timeout), close: () => cell.close() };
+    return { read: (signal) => cell.read(signal), transact: (fn, signal) => cell.transact(fn, signal), changed: (since, timeout) => cell.changed(since, timeout), close: () => cell.close() };
 }
 export async function waitForSquareChanges(squarePaths, timeoutMs, signal, afterReady, onArmed) {
     if (timeoutMs <= 0 || signal?.aborted || squarePaths.length === 0) {

package/dist/square-storage.d.ts

@@ -12,6 +12,6 @@ export declare function createSquareSnapshot(squarePath: string, squareState: Sq
 /** In-process cell for fast behavior tests and embedded consumers. */
 export declare function createMemoryCell(initial: SquareState): StateCell;
 /** SQLite-backed cell. Revisions are read from the authoritative database, not file metadata. */
-export declare function createFileCell(squarePath: string): StateCell;
+export declare function createFileCell(squarePath: string, externalSignal?: AbortSignal): StateCell;
 /** Consumer-facing file cell factory; keeps SQLite framing behind this module. */
-export declare function openSquareCell(squarePath: string): StateCell;
+export declare function openSquareCell(squarePath: string, signal?: AbortSignal): StateCell;

package/dist/square-storage.js

@@ -69,10 +69,14 @@ export function createMemoryCell(initial) {
         }
     }
     return {
-        transact(fn) {
+        transact(fn, signal) {
             assertCellOpen(closed);
+            if (signal?.aborted)
+                throw signal.reason ?? new Error('StateCell operation aborted');
             const operation = tail.then(() => {
                 assertCellOpen(closed);
+                if (signal?.aborted)
+                    throw signal.reason ?? new Error('StateCell operation aborted');
                 const current = cloneState(state);
                 const outcome = fn(current, version);
                 if (isThenable(outcome)) {
@@ -92,10 +96,14 @@ export function createMemoryCell(initial) {
             tail = operation.then(() => undefined, () => undefined);
             return operation;
         },
-        async read() {
+        async read(signal) {
             assertCellOpen(closed);
+            if (signal?.aborted)
+                throw signal.reason ?? new Error('StateCell operation aborted');
             await tail;
             assertCellOpen(closed);
+            if (signal?.aborted)
+                throw signal.reason ?? new Error('StateCell operation aborted');
             return { state: cloneState(state), version };
         },
         changed(sinceVersion, timeoutMs) {
@@ -127,7 +135,7 @@ export function createMemoryCell(initial) {
     };
 }
 /** SQLite-backed cell. Revisions are read from the authoritative database, not file metadata. */
-export function createFileCell(squarePath) {
+export function createFileCell(squarePath, externalSignal) {
     let closed = false;
     let storage;
     let tail = Promise.resolve();
@@ -139,22 +147,29 @@ export function createFileCell(squarePath) {
     function abortError() {
         return new Error('StateCell is closed');
     }
+    /** Close wins over every operation; a per-call deadline bounds busy retries alongside it. */
+    function operationSignal(signal) {
+        if (signal === undefined && externalSignal === undefined)
+            return cancel.signal;
+        return AbortSignal.any([cancel.signal, ...(externalSignal === undefined ? [] : [externalSignal]), ...(signal === undefined ? [] : [signal])]);
+    }
     return {
-        transact(fn) {
+        transact(fn, signal) {
             assertCellOpen(closed);
+            const opSignal = operationSignal(signal);
             const operation = tail.then(async () => {
                 assertCellOpen(closed);
-                const result = await transactSquareSnapshot(await storagePath(), fn, cancel.signal);
+                const result = await transactSquareSnapshot(await storagePath(), fn, opSignal);
                 return result.result;
             });
             tail = operation.then(() => undefined, () => undefined);
             return operation;
         },
-        async read() {
+        async read(signal) {
             assertCellOpen(closed);
             await tail;
             assertCellOpen(closed);
-            const snapshot = await readSquareSnapshot(await storagePath(), cancel.signal);
+            const snapshot = await readSquareSnapshot(await storagePath(), operationSignal(signal));
             return { state: cloneState(snapshot.state), version: snapshot.revision };
         },
         async changed(sinceVersion, timeoutMs) {
@@ -198,6 +213,6 @@ export function createFileCell(squarePath) {
     };
 }
 /** Consumer-facing file cell factory; keeps SQLite framing behind this module. */
-export function openSquareCell(squarePath) {
-    return createFileCell(squarePath);
+export function openSquareCell(squarePath, signal) {
+    return createFileCell(squarePath, signal);
 }

package/dist/state-cell.d.ts

@@ -4,8 +4,8 @@ export interface StateCell {
     transact<R>(fn: (state: SquareState, version: number) => {
         state?: SquareState;
         result: R;
-    }): Promise<R>;
-    read(): Promise<{
+    }, signal?: AbortSignal): Promise<R>;
+    read(signal?: AbortSignal): Promise<{
         state: SquareState;
         version: number;
     }>;

package/extensions/square-pi.js

@@ -29,9 +29,23 @@ export function renderPiInbox(inbox) {
   return renderPendingAtBoundary(pendingInbox(inbox));
 }
 
+const NOTIFY_BODY_MAX = 80;
+
+export function summarizePendingForNotify(pending) {
+  const lines = pending.flatMap((membership) => membership.notifications.map((note) => {
+    const verb = note.route === 'bell' ? 'rang the bell for' : note.route === 'mention' ? 'walked over to' : 'paid attention to';
+    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} ${membership.name}${clipped ? ` — ${clipped}` : ''}`;
+  }));
+  if (lines.length === 0) return undefined;
+  return lines.length === 1 ? `■ square · ${lines[0]}` : `■ square · ${lines[0]} (+${lines.length - 1} more)`;
+}
+
 export default function squarePiExtension(pi) {
   let sessionId;
   let sessionCwd;
+  let ui;
   let watcher;
   let watcherAbort;
   let generation = 0;
@@ -185,10 +199,14 @@ export default function squarePiExtension(pi) {
           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 landing = waitForLanding(content, signal, 'steer');
             try {
               Promise.resolve(pi.sendMessage(
-                { customType: 'square', content, display: true },
+                { customType: 'square', content, display: false },
                 { deliverAs: 'steer', triggerTurn: true },
               )).catch((error) => landing.ack.settle(error));
             } catch (error) {
@@ -240,6 +258,7 @@ export default function squarePiExtension(pi) {
     turnIndex = 0;
     activeTurn = undefined;
     currentRunSignal = undefined;
+    ui = ctx?.ui;
     sessionId = ctx.sessionManager.getSessionId();
     sessionCwd = ctx.cwd || process.cwd();
     const token = generation;
@@ -327,6 +346,7 @@ export default function squarePiExtension(pi) {
     generation += 1;
     failAcks(new Error('Pi session ended'));
     stopWatcher();
+    ui = undefined;
     if (sessionId && sessionCwd) void automaticSessionEnd('pi', sessionId, sessionCwd, sessionEnv(sessionId)).catch(() => undefined);
     sessionId = undefined;
     sessionCwd = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.54",
+  "version": "0.3.56",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
@@ -18,8 +18,9 @@
     "clean": "node --input-type=module -e \"import fs from 'node:fs'; fs.rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc && node --input-type=module -e \"import fs from 'node:fs'; fs.chmodSync('dist/square.js',0o755)\"",
     "verify-release": "node test/release.test.js",
-    "release": "npm version patch && npm publish && git push --follow-tags",
-    "prepublishOnly": "npm run build && npm run verify-release",
+    "sync-manifests": "node scripts/sync-manifests.mjs",
+    "release": "npm version patch && npm run sync-manifests -- --commit && npm publish && git push --follow-tags",
+    "prepublishOnly": "npm run sync-manifests && npm run build && npm run verify-release",
     "test": "npm run build && node --test test/*.test.js",
     "test:cli-process": "npm run build && node --test test/process/square-cli-render.test.js"
   },