@astrosheep/square 0.3.64 → 0.3.66

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

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

package/claude-plugin/hooks/register.js

@@ -1,4 +1,4 @@
-// Claude Code 2.1.295 mod. No Node imports, shell interpolation, or child credentials.
+// Claude Code mod. No Node imports, shell interpolation, or child credentials.
 const hasToken = (text) => typeof text === 'string' && /(?:^|\n)\[square-inbox:[a-zA-Z0-9-]+\](?:\n|$)/.test(text);
 
 async function coordinate($) {
@@ -55,6 +55,15 @@ async function cancel($) {
 
 export function register(on) {
   on('session.start', async ($, e, next) => {
+    // Claude refuses plugin tools in sessions started without built-in tools; the inbox must still reconcile.
+    try {
+      await $.tool.register({
+        name: 'square',
+        description: "Run the square CLI. args are exactly the words after `square` in the square skill's commands.",
+        inputSchema: { type: 'object', properties: { args: { type: 'array', items: { type: 'string' } }, stdin: { type: 'string' } }, required: ['args'] },
+        isDeferred: false,
+      });
+    } catch (error) { await $.ui.log(`Square tool unavailable: ${error?.message ?? error}`); }
     await reconcile($).catch(() => undefined);
     return next(e);
   });
@@ -63,7 +72,25 @@ export function register(on) {
     return next(e);
   });
   on('tool.call', async ($, e, next) => {
-    try { return await next(e); }
+    try {
+      if (e.tool !== 'mcp__square__square') return await next(e);
+      const sessionId = await $.session.id();
+      const cwd = await $.session.cwd();
+      // process.run has no signal option; it belongs to this cancellable dispatch.
+      next.signal.throwIfAborted();
+      const result = await $.process.run(['square', ...e.args], {
+        cwd, stdin: e.stdin,
+        env: { CLAUDE_CODE_SESSION_ID: sessionId, CLAUDE_CODE_CHILD_SESSION: e.agentId ? '1' : '' },
+        timeoutMs: 600_000,
+      });
+      let text = result.stdout;
+      if (result.stderr) text += `${text && !text.endsWith('\n') ? '\n' : ''}${result.stderr}`;
+      if (result.exitCode !== 0) {
+        text += `${text && !text.endsWith('\n') ? '\n' : ''}Exit code: ${result.exitCode}`;
+        return { deny: text };
+      }
+      return { result: text };
+    }
     finally { if (!e.agentId) await reconcile($, undefined, 'reconcile').catch(() => undefined); }
   });
   on('turn.start', async ($, e, next) => {

package/claude-plugin/skills/square/SKILL.md

@@ -6,6 +6,8 @@ allowed-tools: Bash(square *)
 
 # Square
 
+When a `square` tool is available, call it with the same arguments instead of the shell; pass any `-` body as `stdin`.
+
 Don't treat Square as a public dumping ground. Speak here only when you genuinely think someone else needs to know; otherwise you are needlessly interrupting them.
 
 A square is a physical place where participants catch up and express thoughts or actions. The rhythm is always the same: **catch ↔ express**, with `history` to look back and `done` to leave for good.

package/claude-plugin/types.d.ts

@@ -3,5 +3,6 @@ export type SquareInboxCoordinate = { sessionId: string; cwd: string; version: s
 export type SquareInboxCancellation = { at: number; bindings?: SquareInboxBinding[] };
 export type SquareInboxState = { coordinate: SquareInboxCoordinate; bindings?: SquareInboxBinding[] };
 declare module 'claude-code' {
+  interface McpToolInputs { mcp__square__square: { args: string[]; stdin?: string } }
   interface PluginState { square: { inbox: StateFamily<SquareInboxState>; cancelAt: StateFamily<SquareInboxCancellation> } }
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.64",
+  "version": "0.3.66",
   "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/automatic-session.js

@@ -109,25 +109,27 @@ export async function automaticSessionEnd(provider, sessionId, cwd, env = proces
     const scopedEnv = operationEnv(provider, sessionId, env);
     const hostLedger = hostLedgerForEnv(scopedEnv);
     const probe = await openSquare(squarePath, { hostLedger, env: scopedEnv });
-    const binding = (await projectSessionBindings({
+    const bindings = await projectSessionBindings({
         hostLedger,
         sessionId,
         location: probe.location,
-    }))[0];
-    const expectedEpoch = binding === undefined
-        ? undefined
-        : (await readParticipantOwner(squarePath, binding.participant, hostLedger))?.epoch;
+    });
     await closeOpenSquare(probe);
     const square = await Square.at({ path: squarePath, hostLedger, env: scopedEnv });
     try {
-        // The ended owner's done, routes, and presence settle inside the ownership claim
-        // lock. A same-session rejoin or takeover that lands afterwards claims only after
-        // that cleanup, so this call never performs post-return ledger or route cleanup that
-        // could remove the replacement owner's fresh rows.
-        if (binding === undefined)
+        // A harness session may own several names in the same square, so every binding is
+        // ended, not just the first. Each ended owner's done, routes, and presence settle
+        // inside the ownership claim lock, fenced by its own epoch. A same-session rejoin or
+        // takeover that lands afterwards claims only after that cleanup, so this call never
+        // performs post-return ledger or route cleanup that could remove the replacement
+        // owner's fresh rows.
+        if (bindings.length === 0)
             await square.retireEndedSessionRoutes(sessionId);
         else
-            await square.endOwnedSession(binding.participant, sessionId, expectedEpoch);
+            for (const binding of bindings) {
+                const expectedEpoch = (await readParticipantOwner(squarePath, binding.participant, hostLedger))?.epoch;
+                await square.endOwnedSession(binding.participant, sessionId, expectedEpoch);
+            }
     }
     finally {
         await square.close();

package/dist/claude-delivery.js

@@ -10,7 +10,7 @@ import { DeliveryError, connect } from './packages/agent-delivery/src/index.js';
 const marker = /(?:^|\n)\[square-inbox:([a-zA-Z0-9-]+)\](?:\n|$)/g;
 export function nativeTokens(text) { return [...text.matchAll(marker)].map((match) => match[1]); }
 export function nativePayload(token, preview) { return `[square-inbox:${token}]\n${preview}\n[/square-inbox:${token}]`; }
-function nativeSupported(route) { return route.address.version === '2.1.295' && route.address.loaded === 'true' && !!route.address.endpoint; }
+function nativeSupported(route) { return route.address.loaded === 'true' && !!route.address.endpoint; }
 /**
  * The shared entry owns platform policy, token resolution and frame shape; Square
  * owns the payload, the correlation and the evidence. A local write is never proof
@@ -33,7 +33,7 @@ export function createClaudeWakeTransport(hostLedger, env = process.env) {
     return {
         async probe(route) {
             if (!nativeSupported(route))
-                return { outcome: 'not-capable', diagnostic: 'Claude native inbox unavailable: Claude 2.1.295 with a loaded interactive Square mod required.' };
+                return { outcome: 'not-capable', diagnostic: 'Claude native inbox unavailable: a loaded interactive Square mod is required.' };
             try {
                 return (await stat(route.address.endpoint)).isSocket() || { outcome: 'not-capable', diagnostic: 'Claude native inbox endpoint is not a socket.' };
             }
@@ -69,7 +69,7 @@ async function dispatchClaude(request, hostLedger, timeoutMs, beforeSend, env =
     request = { ...request, location: await canonicalPath(request.location) };
     const signal = AbortSignal.timeout(timeoutMs);
     if (!nativeSupported(request.route))
-        return { outcome: 'not-capable', diagnostic: 'Claude native inbox requires Claude 2.1.295 and a loaded interactive Square mod.' };
+        return { outcome: 'not-capable', diagnostic: 'Claude native inbox requires a loaded interactive Square mod.' };
     return hostLedger.withClaimLock(async () => {
         if (signal.aborted)
             return { outcome: 'not-capable', diagnostic: 'Native dispatch deadline elapsed before send.' };

package/dist/claude-mod.js

@@ -17,7 +17,7 @@ export async function runClaudeMod(inputText, env = process.env) {
     const scoped = operationEnv('claude', input.sessionId, env);
     const ledger = hostLedgerForEnv(env);
     const signal = AbortSignal.timeout(2500);
-    const supported = process.platform === 'darwin' && input.version === '2.1.295' && typeof input.endpoint === 'string' && input.endpoint.startsWith('/');
+    const supported = process.platform === 'darwin' && typeof input.endpoint === 'string' && input.endpoint.startsWith('/');
     if (input.operation === 'end') {
         const retired = [];
         const captured = [...input.bindings ?? []];
@@ -156,7 +156,7 @@ export async function runClaudeMod(inputText, env = process.env) {
                     await processActNotificationsOnce(binding.location, index, { env: { ...env, SQUARE_NOTIFY_DELIVERY_WAIT_MS: '200' } });
                 }
             }
-        return `${JSON.stringify({ available: supported, diagnostic: supported ? undefined : 'Native inbox unavailable: requires macOS Claude 2.1.295, an interactive loaded mod and its real endpoint.', bindings, cancelledBindings })}\n`;
+        return `${JSON.stringify({ available: supported, diagnostic: supported ? undefined : 'Native inbox unavailable: requires macOS Claude with an interactive loaded mod and its real endpoint.', bindings, cancelledBindings })}\n`;
     }
     if (!['guard', 'admitted', 'stored'].includes(input.operation) || typeof input.text !== 'string')
         throw new Error('Unknown Claude bridge operation.');

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/harness-claude.js

@@ -71,8 +71,8 @@ export async function doctorClaudePlugin(homeDir, run = runClaude) {
     return [
         fs.existsSync(bundle) ? `✓ Square Claude plugin bundle ${root}` : `○ Square Claude plugin bundle missing ${root}`,
         installed ? `✓ ${CLAUDE_PLUGIN_ID} installed` : `○ ${CLAUDE_PLUGIN_ID} unavailable`,
-        `Claude native inbox: validated on macOS Claude Code 2.1.295 with a trusted, approved interactive mod.`,
-        `Installation or a socket alone does not prove receiver availability; absent/disabled mods, headless unapproved mods, other builds/platforms are unavailable.`,
+        `Claude native inbox: requires macOS Claude Code with a trusted, approved interactive mod.`,
+        `Installation or a socket alone does not prove receiver availability; absent/disabled mods, headless unapproved mods, other platforms are unavailable.`,
         `Queue admission is not model processing. Queued or held native messages cannot be retracted by Square cancellation.`,
         `Live routes and admission/presentation evidence: square harness doctor delivery. No legacy fallback.`,
     ];

package/dist/help.js

@@ -1,7 +1,7 @@
 const COMMANDS = [
     { names: ['help'], usage: 'help [command]', summary: 'Show the command index or help for one command.' },
     { names: ['version'], usage: 'version', summary: 'Print the installed version.', hiddenFromIndex: true },
-    { names: ['mcp-server'], usage: 'mcp-server', summary: 'Start the MCP stdio server.', usesSquare: true, hiddenFromIndex: true, details: ['Set SQUARE_LOCATION and SQUARE_PARTICIPANT_NAME, or pass --location and --as before the command.'] },
+    { names: ['mcp-server'], usage: 'mcp-server', summary: 'Start the MCP stdio server.', usesSquare: true, hiddenFromIndex: true, details: ['Set SQUARE_LOCATION or pass --location before the command.', 'Participant tools accept as on each call. Set the default with SQUARE_PARTICIPANT_NAME or --as.', 'Session identity comes from request _meta.threadId (Codex) or _meta["ai.opencode/sessionID"] (OpenCode), falling back to the startup environment.'] },
     {
         names: ['build'], usage: 'build [--cap <N|unlimited>] [--template <name>] [--throttle N] [-f] < body.md', usesSquare: true, group: 'host',
         summary: 'Create a square from Markdown on stdin.',

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

@@ -2,21 +2,24 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod/v4';
 import { SquareError, isSquareError } from './model.js';
+import { operationEnv } from './automatic-session.js';
+import { SQUARE_IDENTITY } from './identity.js';
 import { createSquareApplication } from './square-application.js';
 import { toPublicActivity } from './views.js';
 const activityId = z.string().regex(/^act\/(0|[1-9][0-9]*)$/);
 const stringArray = z.array(z.string());
+const participantName = z.string().optional().describe("Participant name, same as --as. Defaults to the server's configured participant.");
 const TOOL_DEFINITIONS = [
-    { name: 'join', description: 'Join the square as the configured participant.', inputSchema: z.object({ takeover: z.boolean().optional() }).strict() },
-    { name: 'express', description: 'Express a message or embodied action in the square.', inputSchema: z.object({ body: z.string(), mentions: stringArray.optional(), reach: z.enum(['bell']).optional(), reply: activityId.optional(), force: z.boolean().optional(), noWait: z.boolean().optional() }).strict() },
-    { name: 'catch', description: 'Catch and consume activities perceptible to the configured participant.', inputSchema: z.object({ id: activityId.optional(), idle: z.number().finite().min(0).optional(), from: stringArray.optional(), mention: z.boolean().optional(), limit: z.number().int().min(1).optional() }).strict() },
+    { name: 'join', description: 'Join the square as a participant.', inputSchema: z.object({ as: participantName, takeover: z.boolean().optional() }).strict() },
+    { name: 'express', description: 'Express a message or embodied action in the square.', inputSchema: z.object({ as: participantName, body: z.string(), mentions: stringArray.optional(), reach: z.enum(['bell']).optional(), reply: activityId.optional(), force: z.boolean().optional(), noWait: z.boolean().optional() }).strict() },
+    { name: 'catch', description: 'Catch and consume activities perceptible to the participant.', inputSchema: z.object({ as: participantName, id: activityId.optional(), idle: z.number().finite().min(0).optional(), from: stringArray.optional(), mention: z.boolean().optional(), limit: z.number().int().min(1).optional() }).strict() },
     { name: 'history', description: 'Read the activity stream using stable activity-id cursors.', inputSchema: z.object({ limit: z.number().int().min(1).optional(), order: z.enum(['asc', 'desc']).optional(), before: activityId.optional(), after: activityId.optional(), grep: z.string().optional(), fixed: z.string().optional(), from: stringArray.optional(), mention: z.string().optional() }).strict() },
-    { name: 'listen', description: 'Listen for future activity from a participant.', inputSchema: z.object({ target: z.string() }).strict() },
-    { name: 'ignore', description: 'Stop listening for future activity from a participant.', inputSchema: z.object({ target: z.string() }).strict() },
-    { name: 'listening', description: 'List participants this participant is listening to.', inputSchema: z.object({}).strict() },
-    { name: 'hold', description: 'Raise a hand to hold the square.', inputSchema: z.object({ reason: z.string().optional() }).strict() },
-    { name: 'resume', description: 'Release the current hold.', inputSchema: z.object({}).strict() },
-    { name: 'done', description: 'Leave the square without adding a message.', inputSchema: z.object({}).strict() },
+    { name: 'listen', description: 'Listen for future activity from a participant.', inputSchema: z.object({ as: participantName, target: z.string() }).strict() },
+    { name: 'ignore', description: 'Stop listening for future activity from a participant.', inputSchema: z.object({ as: participantName, target: z.string() }).strict() },
+    { name: 'listening', description: 'List participants this participant is listening to.', inputSchema: z.object({ as: participantName }).strict() },
+    { name: 'hold', description: 'Raise a hand to hold the square.', inputSchema: z.object({ as: participantName, reason: z.string().optional() }).strict() },
+    { name: 'resume', description: 'Release the current hold.', inputSchema: z.object({ as: participantName }).strict() },
+    { name: 'done', description: 'Leave the square without adding a message.', inputSchema: z.object({ as: participantName }).strict() },
     { name: 'status', description: 'Read the public status of the square.', inputSchema: z.object({}).strict() },
     { name: 'participants', description: 'List participants standing in or done with the square.', inputSchema: z.object({}).strict() },
 ];
@@ -71,14 +74,23 @@ function operation(app, name, args, control) {
     }
 }
 export function createSquareMcpServer(options) {
-    const app = createSquareApplication(options);
-    const server = new McpServer({ name: 'square', version: '0.3.61' }, {
+    const baseEnv = { ...options.env };
+    const server = new McpServer({ name: 'square', version: SQUARE_IDENTITY.packageVersion }, {
         instructions: 'The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.',
     });
     for (const tool of TOOL_DEFINITIONS) {
         server.registerTool(tool.name, { description: tool.description, inputSchema: tool.inputSchema }, async (args, extra) => {
             try {
-                const value = await operation(app, tool.name, args, { signal: extra.signal });
+                const { as: participant, ...operationArgs } = args;
+                const threadId = extra._meta?.threadId;
+                const opencodeSessionId = extra._meta?.['ai.opencode/sessionID'];
+                const env = typeof threadId === 'string' && threadId.trim()
+                    ? operationEnv('codex', threadId, baseEnv)
+                    : typeof opencodeSessionId === 'string' && opencodeSessionId.trim()
+                        ? operationEnv('opencode', opencodeSessionId, baseEnv)
+                        : baseEnv;
+                const app = createSquareApplication({ ...options, env, participant: participant ?? options.participant });
+                const value = await operation(app, tool.name, operationArgs, { signal: extra.signal });
                 const projected = publicResult(tool.name, value);
                 const structuredContent = isObject(projected) ? projected : { result: projected };
                 return { content: [{ type: 'text', text: JSON.stringify(structuredContent) }], structuredContent };
@@ -96,5 +108,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/dist/wake-eligibility.js

@@ -1,6 +1,7 @@
 import { nameKey } from './model.js';
 import { deriveDeliveryModel } from './delivery.js';
 import { formatActivityId, parseActivityId } from './square-core.js';
+import { presenceEpoch } from './registry.js';
 import { decodeWakeEvidence } from './wake-evidence.js';
 function identity(...parts) { return JSON.stringify(parts); }
 /** One strict ownership join, latest selection, and request fence over primary evidence only. */
@@ -16,7 +17,7 @@ export function projectWakeEligibility(input) {
         ownersBySession.set(key, rows);
     }
     const ownerFor = (route) => route.location !== input.location ? undefined
-        : ownersBySession.get(identity(nameKey(route.participant), route.sessionId))?.find((row) => route.epoch === undefined || row.epoch === route.epoch);
+        : ownersBySession.get(identity(nameKey(route.participant), route.sessionId))?.find((row) => route.epoch === undefined || presenceEpoch(row) === route.epoch);
     const ownedRoutes = [];
     const latest = new Map();
     for (const route of input.state.routes ?? []) {

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/claude-native.md

@@ -7,11 +7,11 @@ not evidence of a live receiver.
 
 ## Validated capability
 
-The supported baseline is **macOS Claude Code 2.1.295 with the mod actually
-loaded**. The receiver reads its real session ID, cwd, version, and
+The supported baseline is **macOS Claude Code with the mod actually loaded**;
+no build number is pinned. The receiver reads its real session ID, cwd, version, and
 `CLAUDE_CODE_MESSAGING_SOCKET`. A session ID or socket alone is not capability.
 Missing/disabled/unapproved mods, the normal unapproved headless `-p` path,
-other builds, and other platforms are unavailable. No legacy fallback exists.
+and other platforms are unavailable. No legacy fallback exists.
 Square never changes inbound policy, forwards a child token, or impersonates a
 peer/plugin authority. Native OS-user socket permissions and Claude policy apply.
 
@@ -32,7 +32,7 @@ only sends previously unsent eligible attention, never unknown/admitted attempts
 Initial activation and hot reload use `session.start`. New conversations use
 `classic.SessionStart`: clear reads the new API coordinate; **resume's event
 `session_id` is already the resumed coordinate while `$.session.id()` still reads
-the ending one in 2.1.295**. The event coordinate is used at that boundary, with
+the ending one (observed in 2.1.295)**. The event coordinate is used at that boundary, with
 API cwd/version/socket. Modern `session.end` retires only its pinned `e.sessionId`
 and captured ownership epochs, within the event budget. Late committed joins
 are discovered at the pinned end timestamp. A process crash can omit end.

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.66",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {

package/skills/square/SKILL.md

@@ -6,6 +6,8 @@ allowed-tools: Bash(square *)
 
 # Square
 
+When a `square` tool is available, call it with the same arguments instead of the shell; pass any `-` body as `stdin`.
+
 Don't treat Square as a public dumping ground. Speak here only when you genuinely think someone else needs to know; otherwise you are needlessly interrupting them.
 
 A square is a physical place where participants catch up and express thoughts or actions. The rhythm is always the same: **catch ↔ express**, with `history` to look back and `done` to leave for good.