@astrosheep/square 0.3.64 → 0.3.65

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

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

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

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

package/dist/artifact.d.ts

@@ -23,7 +23,7 @@ export declare function readSquareSnapshot(squarePath: string, signal?: AbortSig
 /** Check the artifact revision without loading or parsing the historical state. */
 export declare function readSquareRevision(squarePath: string, signal?: AbortSignal): Promise<number>;
 /** One reference-counted revision detector per canonical artifact in this process. */
-export declare function observeSquareRevision(squarePath: string): Promise<import('./file-changes.js').VersionObserver<number>>;
+export declare function observeSquareRevision(squarePath: string): Promise<import('./file-changes.js').VersionObserver<number | null>>;
 export type SquareTransition<R> = (state: SquareState, revision: number) => {
     state?: SquareState;
     result: R;

package/dist/artifact.js

@@ -251,7 +251,18 @@ export function readSquareRevision(squarePath, signal) {
 }
 /** One reference-counted revision detector per canonical artifact in this process. */
 export function observeSquareRevision(squarePath) {
-    return observeFileVersion(squarePath, 'square-revision', readSquareRevision);
+    return observeFileVersion(squarePath, 'square-revision', async (file, signal) => {
+        try {
+            return await readSquareRevision(file, signal);
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw signal.reason ?? error;
+            if (error instanceof InternalSquareError && error.code === 'not_found')
+                return null;
+            throw error;
+        }
+    });
 }
 async function readWithBusyRetry(read, signal) {
     while (true) {

package/dist/codex-boundary-state.d.ts

@@ -4,5 +4,5 @@ export interface CodexBoundary {
 }
 export declare function readCodexBoundary(threadId: string, env?: NodeJS.ProcessEnv): Promise<CodexBoundary | undefined>;
 export declare function codexQueueEligible(threadId: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
-export declare function recordCodexBoundary(threadId: string, event: 'Stop' | 'non-stop', env?: NodeJS.ProcessEnv): Promise<void>;
-export declare function clearCodexBoundary(threadId: string, env?: NodeJS.ProcessEnv): Promise<void>;
+export declare function recordCodexBoundary(threadId: string, event: 'Stop' | 'non-stop', env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<void>;
+export declare function clearCodexBoundary(threadId: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<void>;

package/dist/codex-boundary-state.js

@@ -59,11 +59,11 @@ export async function codexQueueEligible(threadId, env = process.env) {
     const boundary = await readCodexBoundary(threadId, env);
     return boundary !== undefined && boundary.lastStop > boundary.lastNonStop;
 }
-export async function recordCodexBoundary(threadId, event, env = process.env) {
+export async function recordCodexBoundary(threadId, event, env = process.env, signal) {
     if (!threadId)
         return;
     const filePath = statePath(env);
-    await withFileLock(lockPath(filePath), { retryMs: 10 }, async () => {
+    await withFileLock(lockPath(filePath), { retryMs: 10, signal }, async () => {
         const value = await readFile(filePath);
         value.nextSequence += 1;
         const current = value.threads[threadId] ?? { lastStop: 0, lastNonStop: 0 };
@@ -73,11 +73,11 @@ export async function recordCodexBoundary(threadId, event, env = process.env) {
         await writeFile(filePath, value);
     });
 }
-export async function clearCodexBoundary(threadId, env = process.env) {
+export async function clearCodexBoundary(threadId, env = process.env, signal) {
     if (!threadId)
         return;
     const filePath = statePath(env);
-    await withFileLock(lockPath(filePath), { retryMs: 10 }, async () => {
+    await withFileLock(lockPath(filePath), { retryMs: 10, signal }, async () => {
         const value = await readFile(filePath);
         if (!(threadId in value.threads))
             return;

package/dist/codex-hook.js

@@ -35,7 +35,7 @@ export async function codexHookResponse(input, lookup = sessionInbox, env = proc
     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);
+    await recordCodexBoundary(input.session_id, hookEventName === 'Stop' ? 'Stop' : 'non-stop', env, signal);
     stage('boundary-record');
     if (hookEventName === 'Stop') {
         await sweepPrivilegedPending(cwd, env, deliveryAdapters, sweepDeadline, signal).catch(() => undefined);
@@ -82,7 +82,7 @@ export async function runCodexHookAsync(inputText, env = process.env) {
     if (typeof value.session_id !== 'string')
         return runCodexHook(inputText, env);
     if (value.hook_event_name === 'SessionStart' || value.hook_event_name === 'SessionResume') {
-        await recordCodexBoundary(value.session_id, 'non-stop', env);
+        await recordCodexBoundary(value.session_id, 'non-stop', env, AbortSignal.timeout(hookBudgetMs(env)));
         const cwd = typeof value.cwd === 'string' ? value.cwd : process.cwd();
         try {
             const context = await automaticSessionStart('codex', value.session_id, cwd, env);
@@ -93,7 +93,7 @@ export async function runCodexHookAsync(inputText, env = process.env) {
         }
     }
     if (value.hook_event_name === 'SessionEnd') {
-        await clearCodexBoundary(value.session_id, env);
+        await clearCodexBoundary(value.session_id, env, AbortSignal.timeout(hookBudgetMs(env)));
         const cwd = typeof value.cwd === 'string' ? value.cwd : process.cwd();
         try {
             await automaticSessionEnd('codex', value.session_id, cwd, env);

package/dist/inbox.js

@@ -1,3 +1,4 @@
+import { nameKey } from './model.js';
 import { openSquareArtifact, observeSquareChanges } from './square-file-adapter.js';
 import { hostLedgerForEnv } from './registry.js';
 import { canonicalPath } from './canonical-path.js';
@@ -6,29 +7,36 @@ import { WATCH_STALE_MS } from './runtime.js';
 function notificationKey(membership, actIndex) {
     return membership.squarePath + '\0' + membership.name.toLocaleLowerCase() + '\0' + actIndex;
 }
+async function readInboxMembership(binding, signal) {
+    const artifact = openSquareArtifact(binding.location, signal);
+    try {
+        const projection = await projectPresentation({ artifact, binding, now: Date.now() });
+        if (!projection.joined)
+            return undefined;
+        return { name: projection.binding.participant, squarePath: projection.binding.location,
+            notifications: [...projection.notifications],
+            ...(projection.catchLease === undefined ? {} : { catchLease: projection.catchLease }) };
+    }
+    finally {
+        await artifact.close();
+    }
+}
 export async function sessionInbox(sessionId, env = process.env, signal) {
     const inbox = [];
     const hostLedger = hostLedgerForEnv(env);
     for (const binding of await projectSessionBindings({ hostLedger, sessionId })) {
         if (signal?.aborted)
             throw signal.reason;
-        const artifact = openSquareArtifact(binding.location, signal);
         try {
-            const projection = await projectPresentation({ artifact, binding, now: Date.now() });
-            if (!projection.joined)
-                continue;
-            inbox.push({ name: projection.binding.participant, squarePath: projection.binding.location,
-                notifications: [...projection.notifications],
-                ...(projection.catchLease === undefined ? {} : { catchLease: projection.catchLease }) });
+            const membership = await readInboxMembership(binding, signal);
+            if (membership !== undefined)
+                inbox.push(membership);
         }
         catch (error) {
             if (signal?.aborted)
                 throw signal.reason ?? error;
             // A stale or unreadable membership cannot disable delivery for other memberships.
         }
-        finally {
-            await artifact.close();
-        }
     }
     return inbox;
 }
@@ -36,13 +44,28 @@ async function capture(observer, kind, signal) {
     const generation = observer.generation;
     try {
         const value = await observer.read(signal);
-        return { kind, wait: (timeout, abort) => observer.changed(value, timeout, abort) };
+        return { kind, value, wait: (timeout, abort) => observer.changed(value, timeout, abort) };
     }
     catch (error) {
         if (signal.aborted)
             throw signal.reason ?? error;
-        // Keep watching an unreadable/missing artifact so repair can restore delivery.
-        return { kind, wait: (timeout, abort) => observer.hinted(generation, timeout, abort) };
+        // Failed revision reads are not changes; only a successful retry wakes projection.
+        return { kind, wait: async (timeout, abort) => {
+                const deadline = Date.now() + Math.max(0, timeout);
+                let since = generation;
+                while (await observer.hinted(since, Math.max(0, deadline - Date.now()), abort)) {
+                    since = observer.generation;
+                    try {
+                        await observer.read(abort);
+                        return true;
+                    }
+                    catch (error) {
+                        if (abort.aborted)
+                            throw abort.reason ?? error;
+                    }
+                }
+                return false;
+            } };
     }
 }
 /** Session-scoped projection over process-shared storage change detectors. */
@@ -66,11 +89,11 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
                 while (!signal.aborted) {
                     // Subscribe/capture the ledger BEFORE discovering bindings; a concurrent join cannot fall in a gap.
                     const sources = await Promise.all([capture(ledger.presence, 'presence', signal), capture(ledger.evidence, 'evidence', signal)]);
-                    const bindings = await projectSessionBindings({ hostLedger, sessionId });
-                    const paths = new Set(await Promise.all(bindings.map((binding) => canonicalPath(binding.location))));
-                    for (const [file, observer] of artifacts) {
+                    const bindings = await Promise.all((await projectSessionBindings({ hostLedger, sessionId })).map(async (binding) => ({ ...binding, location: await canonicalPath(binding.location) })));
+                    const paths = new Set(bindings.map((binding) => binding.location));
+                    for (const [file, entry] of artifacts) {
                         if (!paths.has(file)) {
-                            observer.close();
+                            entry.observer.close();
                             artifacts.delete(file);
                         }
                     }
@@ -82,10 +105,42 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
                             observer.close();
                             return [];
                         }
-                        artifacts.set(file, observer);
+                        artifacts.set(file, { observer, inbox: new Map() });
+                    }
+                    for (const [file, entry] of artifacts) {
+                        const source = await capture(entry.observer, 'artifact', signal);
+                        sources.push(source);
+                        if (source.value === undefined || source.value !== entry.revision)
+                            entry.inbox.clear();
+                        entry.revision = source.value;
+                        const names = new Set(bindings.filter((binding) => binding.location === file).map((binding) => nameKey(binding.participant)));
+                        for (const name of entry.inbox.keys())
+                            if (!names.has(name))
+                                entry.inbox.delete(name);
+                    }
+                    const inbox = [];
+                    for (const binding of bindings) {
+                        if (signal.aborted)
+                            return [];
+                        const entry = artifacts.get(binding.location);
+                        const name = nameKey(binding.participant);
+                        try {
+                            if (!entry.inbox.has(name))
+                                entry.inbox.set(name, await readInboxMembership(binding, signal));
+                            const membership = entry.inbox.get(name);
+                            if (membership === undefined)
+                                continue;
+                            const { catchLease, ...rest } = membership;
+                            const now = Date.now();
+                            inbox.push(catchLease !== undefined && catchLease.expiresAt > now && now - catchLease.heartbeatAt <= WATCH_STALE_MS
+                                ? membership : rest);
+                        }
+                        catch (error) {
+                            if (signal.aborted)
+                                throw signal.reason ?? error;
+                            // Unreadable projections are retried, never cached as current.
+                        }
                     }
-                    sources.push(...await Promise.all([...artifacts.values()].map((observer) => capture(observer, 'artifact', signal))));
-                    const inbox = await sessionInbox(sessionId, env, signal);
                     const eligible = await projectBoundaryEligibility({ hostLedger, sessionId, inbox });
                     const excludeKeys = options.excludeKeys;
                     const pending = excludeKeys === undefined ? eligible : eligible.flatMap((membership) => {
@@ -154,8 +209,8 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
             lifetime.abort();
             ledger.presence.close();
             ledger.evidence.close();
-            for (const observer of artifacts.values())
-                observer.close();
+            for (const entry of artifacts.values())
+                entry.observer.close();
             artifacts.clear();
         },
     };

package/dist/mcp.js

@@ -96,5 +96,10 @@ export function createSquareMcpServer(options) {
     return server;
 }
 export async function runSquareMcpStdio(options) {
-    await createSquareMcpServer(options).connect(new StdioServerTransport());
+    const server = createSquareMcpServer(options);
+    const transport = new StdioServerTransport();
+    const close = () => { void server.close(); };
+    process.stdin.once('end', close);
+    process.stdin.once('close', close);
+    await server.connect(transport);
 }

package/dist/opencode.js

@@ -61,12 +61,12 @@ export default {
                     stop(sessionId);
                     continue;
                 }
-                if (receivers.has(sessionId))
+                if (receivers.get(sessionId)?.settled === false)
                     continue;
                 const abort = new AbortController();
                 const signal = AbortSignal.any([lifetime.signal, abort.signal]);
-                const running = receiveOpenCodePending(target, scopedEnv, signal).catch(() => { });
-                receivers.set(sessionId, { abort, running });
+                const receiver = { abort, settled: false, running: receiveOpenCodePending(target, scopedEnv, signal).catch(() => { }).finally(() => { receiver.settled = true; }) };
+                receivers.set(sessionId, receiver);
             }
             for (const sessionId of receivers.keys())
                 if (!candidates.has(sessionId))

package/dist/packages/agent-delivery/src/claude-auth.d.ts

@@ -10,4 +10,4 @@ export interface ClaudeAuthOptions {
  * Explicit token, then the environment token bound to this exact endpoint, then
  * the newest readable peer key for it. Windows requires a token; POSIX does not.
  */
-export declare function resolveClaudeToken(options: ClaudeAuthOptions): Promise<string | undefined>;
+export declare function resolveClaudeToken(options: ClaudeAuthOptions, signal?: AbortSignal): Promise<string | undefined>;

package/dist/packages/agent-delivery/src/claude-auth.js

@@ -11,7 +11,8 @@ function validToken(value) { return typeof value === 'string' && TOKEN.test(valu
  * Explicit token, then the environment token bound to this exact endpoint, then
  * the newest readable peer key for it. Windows requires a token; POSIX does not.
  */
-export async function resolveClaudeToken(options) {
+export async function resolveClaudeToken(options, signal) {
+    signal?.throwIfAborted();
     const endpoint = typeof options.endpoint === 'string' ? parseLocalEndpoint(options.endpoint) : options.endpoint;
     const platform = options.platform ?? process.platform;
     const env = options.env ?? process.env;
@@ -32,6 +33,7 @@ export async function resolveClaudeToken(options) {
     const keys = [];
     try {
         for (const name of await readdir(join(home, 'sessions'))) {
+            signal?.throwIfAborted();
             const match = KEY.exec(name);
             if (!match || match[2] !== digest)
                 continue;
@@ -42,16 +44,19 @@ export async function resolveClaudeToken(options) {
         }
     }
     catch { /* no registry is not an error; it only means no peer key */ }
+    signal?.throwIfAborted();
     keys.sort((a, b) => Number(isAlive(b.pid)) - Number(isAlive(a.pid)) || b.mtimeMs - a.mtimeMs);
     for (const key of keys) {
+        signal?.throwIfAborted();
         try {
-            const value = JSON.parse(await readFile(join(home, 'sessions', key.name), 'utf8'));
+            const value = JSON.parse(await readFile(join(home, 'sessions', key.name), { encoding: 'utf8', signal }));
             if (value && typeof value === 'object' && validToken(value.peerToken)) {
                 return value.peerToken;
             }
         }
         catch { /* the next readable matching key wins */ }
     }
+    signal?.throwIfAborted();
     if (platform === 'win32')
         throw new DeliveryError('authentication_failed', false);
     return undefined;

package/dist/packages/agent-delivery/src/claude-native.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { deadline } from './deadline.js';
+import { DeliveryError } from './errors.js';
 import { connectLocal, LocalEndpointError, parseLocalEndpoint, writeFrames } from './local-endpoint.js';
 import { resolveClaudeToken } from './claude-auth.js';
 const detail = (code) => code === 'aborted' ? 'Native inbox write aborted.'
@@ -26,23 +27,22 @@ export async function writeClaudeNative(target, text, control) {
         return { outcome: 'unavailable', code: 'aborted', message: detail('aborted') };
     if (remaining <= 0)
         return { outcome: 'unavailable', code: 'timeout', message: detail('timeout') };
-    let token;
-    try {
-        token = await resolveClaudeToken({ endpoint, token: target.token, claudeHome: target.claudeHome, env: target.env, platform: target.platform });
-    }
-    catch {
-        return { outcome: 'unavailable', code: 'authentication_failed', message: detail('authentication_failed') };
-    }
-    const frames = [
-        ...(token === undefined ? [] : [{ type: 'auth', token }]),
-        { msgV: 1, msg_id: target.messageId ?? randomUUID(), type: 'user', session_id: target.sessionId, message: { role: 'user', content: text }, priority: 'next' },
-    ];
-    const scope = deadline(Math.min(remaining, 2_147_483_647), control.signal);
+    const scope = deadline(control.deadline - Date.now(), control.signal);
     let socket;
     try {
         scope.check();
-        socket = await connectLocal(endpoint, { signal: scope.signal, timeoutMs: Math.max(1, remaining) });
+        const token = await scope.wait(resolveClaudeToken({ endpoint, token: target.token, claudeHome: target.claudeHome, env: target.env, platform: target.platform }, scope.signal));
+        const frames = [
+            ...(token === undefined ? [] : [{ type: 'auth', token }]),
+            { msgV: 1, msg_id: target.messageId ?? randomUUID(), type: 'user', session_id: target.sessionId, message: { role: 'user', content: text }, priority: 'next' },
+        ];
+        scope.check();
+        if (Date.now() >= control.deadline)
+            throw new LocalEndpointError('timeout');
+        socket = await connectLocal(endpoint, { signal: scope.signal });
         scope.check();
+        if (Date.now() >= control.deadline)
+            throw new LocalEndpointError('timeout');
         // A receiver that never drains must not hold the caller past its deadline.
         await scope.wait(writeFrames(socket, frames));
         scope.check();
@@ -50,7 +50,10 @@ export async function writeClaudeNative(target, text, control) {
     }
     catch (error) {
         const local = error instanceof LocalEndpointError ? error : undefined;
-        const code = scope.code ?? local?.code;
+        const code = scope.code ?? (error instanceof DeliveryError ? error.code : local?.code);
+        if (code === 'authentication_failed') {
+            return { outcome: 'unavailable', code, message: detail(code) };
+        }
         if (code === 'aborted' || code === 'timeout') {
             return { outcome: socket ? 'unknown' : 'unavailable', code, message: detail(code) };
         }

package/dist/packages/agent-delivery/src/claude.js

@@ -27,7 +27,7 @@ export async function connectExisting(options) {
     try {
         scope.check();
         // The ambient environment and platform are the only auth coordinates here.
-        const token = await resolveClaudeToken({ endpoint, token: options.token, claudeHome: options.claudeHome });
+        const token = await scope.wait(resolveClaudeToken({ endpoint, token: options.token, claudeHome: options.claudeHome }, scope.signal));
         scope.check();
         const target = Object.freeze({ harness: 'claude', sessionId: options.sessionId });
         coordinates.set(target, { endpoint: options.endpoint, token, claudeHome: options.claudeHome });

package/dist/square-application.js

@@ -32,14 +32,14 @@ export function createSquareApplication(context) {
     const env = { ...context.env };
     const location = () => requireLocation({ ...context, env });
     const hostLedger = context.hostLedger ?? hostLedgerForEnv(env);
-    const open = () => Square.at({ path: location(), clock: context.clock, env, hostLedger, wakeTransport: context.wakeTransport });
+    const open = (control) => Square.at({ path: location(), clock: context.clock, env, hostLedger, wakeTransport: context.wakeTransport }, control);
     async function existing(operation, control) {
         checkControl(control);
         const squarePath = location();
         const participantName = await requireParticipant(context, squarePath, hostLedger, env);
-        const square = await openSquare(squarePath, { clock: context.clock, env, hostLedger, wakeTransport: context.wakeTransport });
+        const square = await openSquare(squarePath, { clock: context.clock, env, hostLedger, wakeTransport: context.wakeTransport }, control);
         try {
-            const { name } = await resolveParticipant(square, participantName);
+            const { name } = await resolveParticipant(square, participantName, control);
             checkControl(control);
             return await operation(square, name);
         }
@@ -49,7 +49,7 @@ export function createSquareApplication(context) {
     }
     async function joined(operation, control) {
         checkControl(control);
-        const square = await open();
+        const square = await open(control);
         try {
             return await operation(await square.join(await requireParticipant(context, square.location, hostLedger, env), control));
         }
@@ -61,10 +61,10 @@ export function createSquareApplication(context) {
         async join(options = {}, control = {}) {
             checkControl(control);
             const squarePath = location();
-            const square = await open();
+            const square = await open(control);
             try {
                 const participantName = await requireParticipant(context, squarePath, hostLedger, env);
-                const before = await square.snapshot();
+                const before = await square.snapshot(control);
                 const standing = before.participants.some((item) => item.name.toLocaleLowerCase() === participantName.toLocaleLowerCase() && item.state === 'joined');
                 const identity = localSessionIdentities(env)[0];
                 const owner = standing ? await readParticipantOwner(squarePath, participantName, hostLedger).catch(() => undefined) : undefined;
@@ -113,7 +113,7 @@ export function createSquareApplication(context) {
                     }
                     else {
                         const waitStarted = Date.now();
-                        const square = await openSquare(location(), { clock: context.clock, env, hostLedger, signal: control.signal });
+                        const square = await openSquare(location(), { clock: context.clock, env, hostLedger }, control);
                         try {
                             const snapshot = await square.artifact.read(control.signal);
                             if (currentHold(snapshot.state.acts).active)
@@ -132,7 +132,7 @@ export function createSquareApplication(context) {
             checkControl(control);
             if (context.participant !== undefined || env.SQUARE_PARTICIPANT_NAME !== undefined)
                 return existing((square, name) => participantHistory(square, name, query, control), control);
-            const square = await open();
+            const square = await open(control);
             try {
                 checkControl(control);
                 return await square.history(query, control);
@@ -153,7 +153,7 @@ export function createSquareApplication(context) {
             const identity = localSessionIdentities(env)[0];
             const owner = identity === undefined ? undefined : await readParticipantOwner(squarePath, participantName, hostLedger).catch(() => undefined);
             if (identity !== undefined && owner?.session === identity.sessionId && presenceEpoch(owner) > 0) {
-                const square = await open();
+                const square = await open(control);
                 try {
                     return await square.doneOwnedSession(participantName, body ?? '', presenceEpoch(owner), control);
                 }

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

@@ -1,6 +1,7 @@
 export { observeSquareRevision as observeSquareChanges } from './artifact.js';
 import { type BuildOptions, type HardCap } from './model.js';
 import type { OpenSquare } from './open-square.js';
+import type { OperationControl } from './square-facade.js';
 import type { HostLedgerPort, SquareArtifactPort } from './ports.js';
 /** File-owned artifact creation for the CLI and path-backed public facade. */
 export declare function createSquare(squarePath: string, options: BuildOptions & {
@@ -17,7 +18,7 @@ export interface SquareBuildOptions {
     /** 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' | 'signal'>): Promise<OpenSquare>;
+export declare function openSquare(squarePath: string, options?: Pick<SquareBuildOptions, 'clock' | 'hostLedger' | 'wakeTransport' | 'env' | 'signal'>, control?: OperationControl): 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

@@ -24,12 +24,12 @@ function validateBuildOptions(options) {
         throw new SquareError('invalid_args', 'throttlePerMinute must be a positive integer');
     }
 }
-export async function openSquare(squarePath, options = {}) {
+export async function openSquare(squarePath, options = {}, control) {
     const env = options.env ?? process.env;
     const ledgerRoot = hostLedgerRoot(env);
     const artifact = openSquareArtifact(squarePath, options.signal);
     try {
-        await artifact.read();
+        await artifact.read(control?.signal);
         return {
             artifact,
             clock: options.clock ?? Date.now,

package/dist/square-projections.js

@@ -21,10 +21,25 @@ export function pendingAtBoundary(inbox) {
  * ledger errors stay exactly as the boundary callers read them.
  */
 export async function projectBoundaryEligibility(input) {
+    const memberships = pendingAtBoundary([...input.inbox]);
+    if (memberships.length === 0)
+        return [];
+    const evidence = await projectPresentationEvidence({ hostLedger: input.hostLedger, sessionId: input.sessionId });
+    const presented = new Map();
+    for (const row of evidence) {
+        if (row.outcome !== 'presented' && row.outcome !== 'clipped')
+            continue;
+        const key = JSON.stringify([row.location, nameKey(row.participant)]);
+        let activities = presented.get(key);
+        if (activities === undefined)
+            presented.set(key, activities = new Set());
+        activities.add(row.activity);
+    }
     const pending = [];
-    for (const membership of pendingAtBoundary([...input.inbox])) {
-        const evidence = await projectPresentationEvidence({ hostLedger: input.hostLedger, location: membership.squarePath, participant: membership.name, sessionId: input.sessionId });
-        const notifications = membership.notifications.filter((notification) => !presentationSuppressesWake(evidence.filter((row) => row.activity === formatActivityId(notification.actIndex))));
+    for (const membership of memberships) {
+        const key = JSON.stringify([await canonicalPath(membership.squarePath), nameKey(membership.name)]);
+        const activities = presented.get(key);
+        const notifications = membership.notifications.filter((notification) => !activities?.has(formatActivityId(notification.actIndex)));
         if (notifications.length > 0)
             pending.push({ ...membership, notifications });
     }
@@ -78,7 +93,8 @@ export async function projectWakeEvidenceFromState(input) {
     const canonicalLocation = await canonicalPath(input.location);
     const delivery = input.delivery ?? deriveDeliveryModel(input.state);
     const owners = await input.hostLedger.listPresence({ location: canonicalLocation, now: input.now });
-    const wakeRecords = await input.hostLedger.listEvidence({ location: canonicalLocation, kind: 'wake', now: input.now });
-    const presentations = await projectPresentationEvidence({ hostLedger: input.hostLedger, location: canonicalLocation, now: input.now });
+    const evidence = await input.hostLedger.listEvidence({ location: canonicalLocation, now: input.now });
+    const wakeRecords = evidence.filter((row) => row.kind === 'wake');
+    const presentations = evidence.filter((row) => row.kind === 'presentation').map((row) => ({ location: row.location, participant: row.participant, sessionId: row.session, activity: row.activity, outcome: row.outcome, ...(row.at === undefined ? {} : { at: row.at }) }));
     return projectWakeEligibility({ state: input.state, location: canonicalLocation, owners, wakeRecords, presentations, now: input.now, delivery });
 }

package/dist/square-wiring.d.ts

@@ -5,7 +5,7 @@ export declare class Square {
     private readonly square;
     private readonly context;
     private constructor();
-    static at(input: SquareAtInput): Promise<Square>;
+    static at(input: SquareAtInput, control?: OperationControl): Promise<Square>;
     static build(input: SquareBuildInput): Promise<Square>;
     static inMemory(input: Omit<SquareBuildInput, 'path'>): Square;
     join(name: string, control?: OperationControl): Promise<Participant>;
@@ -24,7 +24,7 @@ export declare class Square {
         readonly participant?: Participant;
     }>;
     participants(): Promise<ParticipantStatus[]>;
-    snapshot(): Promise<SquareSnapshot>;
+    snapshot(control?: OperationControl): Promise<SquareSnapshot>;
     history(query?: HistoryQuery, control?: OperationControl): Promise<Activity[]>;
     recognize(env: NodeJS.ProcessEnv): Promise<Participant | null>;
     close(): Promise<void>;

package/dist/square-wiring.js

@@ -51,8 +51,8 @@ export class Square {
         this.square = square;
         this.context = { ...square, location };
     }
-    static async at(input) {
-        return new Square(input.path, await openSquare(input.path, input));
+    static async at(input, control) {
+        return new Square(input.path, await openSquare(input.path, input, control));
     }
     static async build(input) {
         return new Square(input.path, await buildSquare(input.path, input));
@@ -85,7 +85,7 @@ export class Square {
             : { state: joined.state, participant: new ParticipantHandle(joined.name, this.square, this.context) };
     }
     participants() { return participants(this.square); }
-    snapshot() { return snapshot(this.square); }
+    snapshot(control) { return snapshot(this.square, control); }
     history(query, control) { return history(this.square, query, control); }
     async recognize(env) {
         if (this.square.hostLedger === undefined)

package/dist/views.d.ts

@@ -69,13 +69,13 @@ export declare function toPublicActivity(stored: StoredAct): Activity;
 export declare function parseRequiredActivityId(id: ActivityId): number;
 export declare function history(square: OpenSquare, query?: HistoryQuery, control?: OperationControl): Promise<Activity[]>;
 export declare function participantHistory(square: OpenSquare, _name: string, query?: HistoryQuery, control?: OperationControl): Promise<Activity[]>;
-export declare function resolveParticipant(square: OpenSquare, name: string): Promise<{
+export declare function resolveParticipant(square: OpenSquare, name: string, control?: OperationControl): Promise<{
     readonly name: string;
     readonly roster: readonly string[];
 }>;
 export declare function currentParticipant(square: OpenSquare, name: string): Promise<string | undefined>;
 export declare function participants(square: OpenSquare): Promise<ParticipantStatus[]>;
-export declare function snapshot(square: OpenSquare): Promise<SquareSnapshot>;
+export declare function snapshot(square: OpenSquare, control?: OperationControl): Promise<SquareSnapshot>;
 export declare function activityPresentation(square: OpenSquare, name: string): Promise<ActivityPresentation>;
 export declare function entryPresentation(square: OpenSquare, name: string, lastN?: number | null): Promise<EntryPresentation>;
 export declare function historyPresentation(square: OpenSquare, options: ActivitiesOptions): Promise<HistoryPresentation>;

package/dist/views.js

@@ -62,10 +62,10 @@ function sayNumbers(state) {
 }
 export async function history(square, query = {}, control) { const { state } = await square.artifact.read(control?.signal); return selectHistory(coreActivities(state, historyOptions(query)), query).map(toPublicActivity); }
 export async function participantHistory(square, _name, query = {}, control) { const { state } = await square.artifact.read(control?.signal); const effective = query.limit !== undefined ? query : { ...query, limit: 10 }; return selectHistory(coreActivities(state, historyOptions(effective)), effective).map(toPublicActivity); }
-export async function resolveParticipant(square, name) { const { state } = await square.artifact.read(); return { name: resolveKnownName(state, name), roster: rosterNames(state) }; }
+export async function resolveParticipant(square, name, control) { const { state } = await square.artifact.read(control?.signal); return { name: resolveKnownName(state, name), roster: rosterNames(state) }; }
 export async function currentParticipant(square, name) { const { state } = await square.artifact.read(); const known = resolveRosterName(state, name); return known !== undefined && isCurrentlyJoined(state.acts, known) ? known : undefined; }
 export async function participants(square) { const { state } = await square.artifact.read(); return statuses(square, state); }
-export async function snapshot(square) { const { state } = await square.artifact.read(); const folded = foldedState(state); return { context: [...state.preamble, ...state.warmup].join('\n'), actCount: state.acts.filter((activity) => activity.kind !== 'read').length, hardCap: state.hardCap, ...(state.throttlePerMinute === undefined ? {} : { throttlePerMinute: state.throttlePerMinute }), held: folded.hold.active && folded.hold.actor !== undefined ? { by: folded.hold.actor, ...(folded.hold.reason === undefined ? {} : { reason: folded.hold.reason }) } : null, participants: statuses(square, state), delivered(name, id) { return isActivitySeen(state, name, parseRequiredActivityId(id)); } }; }
+export async function snapshot(square, control) { const { state } = await square.artifact.read(control?.signal); const folded = foldedState(state); return { context: [...state.preamble, ...state.warmup].join('\n'), actCount: state.acts.filter((activity) => activity.kind !== 'read').length, hardCap: state.hardCap, ...(state.throttlePerMinute === undefined ? {} : { throttlePerMinute: state.throttlePerMinute }), held: folded.hold.active && folded.hold.actor !== undefined ? { by: folded.hold.actor, ...(folded.hold.reason === undefined ? {} : { reason: folded.hold.reason }) } : null, participants: statuses(square, state), delivered(name, id) { return isActivitySeen(state, name, parseRequiredActivityId(id)); } }; }
 export async function activityPresentation(square, name) { const { state } = await square.artifact.read(); const known = resolveKnownName(state, name); const delivery = deriveDeliveryModel(state); const delta = deliveryDelta(state, known, delivery); const hold = currentHold(state.acts); return { name: known, roster: rosterNames(state), pendingPublic: directedPeerSays(state, delta, known, delivery), activities: state.acts, state, participantCount: inSquareCount(state), held: hold.active, ...(hold.reason === undefined ? {} : { holdReason: hold.reason }), ownActivityCount: countSays(state.acts, known), hardCap: state.hardCap }; }
 export async function entryPresentation(square, name, lastN = 10) { const { state } = await square.artifact.read(); const known = resolveRosterName(state, name) ?? name; const publicActivities = state.acts.filter((activity) => activity.kind === 'say' || activity.kind === 'done'); return { joined: isCurrentlyJoined(state.acts, known), scene: state.warmup.join('\n').trim(), context: state.preamble.join('\n').trim(), joinContext: (state.preamble.at(-1) === '---' ? state.preamble.slice(0, -1) : state.preamble).join('\n').trim(), recentActivities: lastN === null ? publicActivities : publicActivities.slice(-lastN), state, sayNumbers: sayNumbers(state), participantCount: inSquareCount(state) }; }
 export async function historyPresentation(square, options) { const { state } = await square.artifact.read(); const delivery = deriveDeliveryModel(state); return { activities: coreActivities(state, options, delivery), sayNumbers: sayNumbers(state), presenceAnchors: anchors(state, delivery), participantCount: inSquareCount(state) }; }

package/extensions/square-pi.js

@@ -120,12 +120,12 @@ export default function squarePiExtension(pi) {
   // Pi owns PI_SESSION_ID and several SDK sessions may coexist in one process.
   const sessionEnv = (id) => ({ ...process.env, ...(id === undefined ? {} : { PI_SESSION_ID: id }) });
 
-  // A transport may keep its promise pending while Pi is shutting down or
-  // replacing a session. Never make a lifecycle hook wait for that transport.
+  // Aborting releases native landing waits; retain cleanup until the observer
+  // has closed, including when cancellation precedes a lifecycle hook.
   const stopWatcher = () => {
     watcherAbort?.abort();
-    watcher = undefined;
     watcherAbort = undefined;
+    return watcher;
   };
 
   const pause = (signal, delayMs) => new Promise((resolve) => {
@@ -229,6 +229,7 @@ export default function squarePiExtension(pi) {
             env,
             signal,
           );
+          if (signal.aborted || token !== generation) return;
           for (const key of keys) handledPending.add(key);
         } catch (error) {
           if (signal.aborted || token !== generation) return;
@@ -252,7 +253,7 @@ export default function squarePiExtension(pi) {
     cancelledRun = false;
     generation += 1;
     failAcks(new Error('Pi session replaced'));
-    stopWatcher();
+    const stopped = stopWatcher();
     handledPending.clear();
     observedPending.clear();
     retryAfterChange = false;
@@ -264,9 +265,11 @@ export default function squarePiExtension(pi) {
     sessionId = ctx.sessionManager.getSessionId();
     sessionCwd = ctx.cwd || process.cwd();
     const token = generation;
+    await stopped;
+    if (token !== generation) return;
     watcherAbort = new AbortController();
     const signal = watcherAbort.signal;
-    void automaticSessionStart('pi', sessionId, sessionCwd, sessionEnv(sessionId)).then((context) => {
+    const startup = automaticSessionStart('pi', sessionId, sessionCwd, sessionEnv(sessionId)).then((context) => {
       if (context === undefined || sessionId === undefined || token !== generation) return;
       const messageContent = framePiMessage(context);
       const landing = waitForLanding(messageContent, signal, 'nextTurn');
@@ -281,7 +284,7 @@ export default function squarePiExtension(pi) {
       }
       void landing.promise.catch(() => undefined);
     }).catch(() => undefined);
-    watcher = wake(token, signal).catch(() => undefined);
+    watcher = Promise.allSettled([startup, wake(token, signal)]).then(() => undefined);
   });
 
   pi.on('agent_start', async (_event, ctx) => {
@@ -334,6 +337,8 @@ export default function squarePiExtension(pi) {
     const token = generation;
     // Cancel the entire pending batch, including entries not yet sent to Pi.
     // This is local suppression, never evidence that the model saw the activity.
+    await stopWatcher();
+    if (token !== generation || sessionId === undefined) return;
     const cancelled = await sessionInbox(sessionId, sessionEnv(sessionId));
     if (token !== generation || sessionId === undefined) return;
     for (const key of inboxKeys(cancelled)) handledPending.add(key);
@@ -348,13 +353,17 @@ export default function squarePiExtension(pi) {
     cancelledRun = false;
     generation += 1;
     failAcks(new Error('Pi session ended'));
-    stopWatcher();
+    const stopped = stopWatcher();
     ui = undefined;
-    if (sessionId && sessionCwd) void automaticSessionEnd('pi', sessionId, sessionCwd, sessionEnv(sessionId)).catch(() => undefined);
+    const endedId = sessionId;
+    const endedCwd = sessionCwd;
+    const endedEnv = sessionEnv(endedId);
     sessionId = undefined;
     sessionCwd = undefined;
     retryWait = undefined;
     activeTurn = undefined;
     currentRunSignal = undefined;
+    await stopped;
+    if (endedId && endedCwd) await automaticSessionEnd('pi', endedId, endedCwd, endedEnv).catch(() => undefined);
   });
 }

package/guides/change-waits.md

@@ -4,7 +4,7 @@ Square's artifact and host-ledger adapters own change detection. Notifications a
 
 - A process shares a revision reader per canonical artifact and a filesystem watcher per containing directory. Subscribers have independent baselines, deadlines, and cancellation. The final release closes the watcher, reconciliation timer, and any outstanding read.
 - Directory notifications invalidate lightweight reads. A two-second reconciliation checks revisions/ledger metadata even when notifications are missing. Missing directories, unsupported watches, and watcher failures retain that fallback; directory replacement is detected during reconciliation. Normal notification latency is not a hard guarantee: a missed hint may wait for reconciliation, plus scheduling and lock contention.
-- The artifact revision remains authoritative. No new sidecar, broker, or persistent cache is introduced. Only changed projections load historical state. Ledger metadata invalidates bindings and presentation projections; it is never treated as evidence of delivery.
+- The artifact revision remains authoritative. No new sidecar, broker, or persistent cache is introduced. Only changed projections load historical state. A missing artifact is a stable observation, not a repeated change: reconciliation remains quiet while it stays absent and detects its return without deleting its session bindings. Strict artifact reads still report absence as an error. Ledger metadata invalidates bindings and presentation projections; it is never treated as evidence of delivery.
 - Each Pi session owns a long-lived pending observer, including when it has no bindings yet. Presence and evidence changes update its subscriptions. There is no repeated thirty-second restart and no per-second binding scan. A failed injection waits for a substantive change; its own failed evidence write does not trigger a retry loop.
 - Blocking CLI catch waits for a revision or its next heartbeat/quiet deadline. A held catch keeps its lease alive and pauses quiet expiry. Core catch, NDJSON stream, and delivery-receipt waits use the same change detector. Held express also waits for changes; throttling still waits for its eligibility time.
 - Catch lease expiry, ledger retention/claim expiry, and cancellation are independent wake conditions. No filesystem write is required for a time-based eligibility change.

package/guides/pi-native-delivery.md

@@ -26,8 +26,14 @@ cross-extension transform compatibility is promised.
 
 Standalone extensions can register `createPiReceiver` from the package's `./pi`
 subpath and use `sendPiMessage` directly. Factory registration creates no
-resources; start/shutdown own them. Raw SDK `dispose()` callers must explicitly
-close the receiver if their host does not emit `session_shutdown`.
+resources; start/shutdown own them. Session replacement and shutdown await the
+pending observer's retirement, including cleanup already begun by run cancellation.
+Cancellation releases native landing waits; it does not leave the observer running
+behind a completed lifecycle hook. Restart after cancellation waits for the old
+observer before opening its successor. Shutdown waits for in-flight automatic
+startup before ending that session, and awaits the session-end work. Raw SDK hosts
+must emit and await `session_shutdown` before `dispose()`;
+disposal alone does not retire extension-owned observers or receivers.
 
 Transport frame/key constraints, client
 `connectExisting`/`sendText` usage, receipt states, bounds and the exact validated

package/package.json

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