@astrosheep/square 0.3.88 → 0.3.89

package/dist/square-stdio.js

@@ -1,10 +1,12 @@
+import { randomUUID } from 'node:crypto';
+import { validateMetadataMatch, validateDeferralDuration, validateDeferralId } from './delivery-deferral.js';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
 import { SquareError } from './model.js';
 import { harnessSessionSources } from './participant-identity.js';
 import { requireJoinName } from './seats.js';
-export const STDIO_PROTOCOL_VERSION = 1;
+export const STDIO_PROTOCOL_VERSION = 2;
 export const STDIO_MAX_FRAME_BYTES = 8 * 1024 * 1024;
 export const identityVariables = [...harnessSessionSources.flatMap(source => [source.variable, ...(source.childVariable ? [source.childVariable] : [])])];
 export function wireIdentity(env) {
@@ -157,33 +159,44 @@ class StdioSquare {
         this.connection = connection;
         this.handle = handle;
     }
-    call(method, args, control, participant) {
-        return this.connection.request(method, { handle: this.handle, args, ...(participant === undefined ? {} : { participant }) }, control);
+    call(method, args, control, participant, participantHandle) {
+        return this.connection.request(method, { handle: this.handle, args, ...(participant === undefined ? {} : { participant, participantHandle }) }, control);
     }
-    participantHandle(name) {
+    participantHandle(name, reference) {
+        const call = (method, args, control) => this.call(method, args, control, name, reference);
         return {
             name,
             express: ((bodyOrInput, optionsOrControl, control) => {
                 if (typeof bodyOrInput === 'object' && bodyOrInput !== null)
-                    return this.call('express', [bodyOrInput, undefined], optionsOrControl, name);
-                return this.call('express', [bodyOrInput, optionsOrControl], control, name);
+                    return call('express', [bodyOrInput, undefined], optionsOrControl);
+                return call('express', [bodyOrInput, optionsOrControl], control);
             }),
-            catch: (options, control) => this.call('catch', [options], control, name),
-            listen: (target, options, control) => this.call('listen', [target, options], control, name),
-            ignore: (target, options, control) => this.call('ignore', [target, options], control, name),
-            unlisten: (target, options, control) => this.call('unlisten', [target, options], control, name),
-            listening: (options, control) => this.call('listening', [options], control, name),
-            hold: (reason, options, control) => this.call('hold', [reason, options], control, name),
-            resume: (options, control) => this.call('resume', [options], control, name),
-            done: (body, options, control) => this.call('done', [body, options], control, name),
+            catch: (options, control) => call('catch', [options], control),
+            listen: (target, options, control) => call('listen', [target, options], control),
+            ignore: (target, options, control) => call('ignore', [target, options], control),
+            unlisten: (target, options, control) => call('unlisten', [target, options], control),
+            listening: (options, control) => call('listening', [options], control),
+            hold: (reason, options, control) => call('hold', [reason, options], control),
+            resume: (options, control) => call('resume', [options], control),
+            done: (body, options, control) => call('done', [body, options], control),
+            deferDelivery: async (input, control) => {
+                const match = validateMetadataMatch(input?.match), durationMs = validateDeferralDuration(input?.durationMs);
+                return call('deferDelivery', [{ match, durationMs }], control);
+            },
+            renewDeliveryDeferral: async (id, durationMs, control) => call('renewDeliveryDeferral', [validateDeferralId(id), validateDeferralDuration(durationMs)], control),
+            releaseDeliveryDeferral: async (id, control) => call('releaseDeliveryDeferral', [validateDeferralId(id)], control),
             history: (query, control) => this.history(query, control),
         };
     }
-    async participant(name) { return this.participantHandle(await this.call('participant', [name])); }
+    async participant(name) {
+        const reference = randomUUID();
+        return this.participantHandle(await this.call('participant', [name, reference]), reference);
+    }
     async join(...[name, options, control]) {
         requireJoinName(name);
-        const result = await this.call('join', [name, options], control);
-        return { ...result, participant: this.participantHandle(result.participant) };
+        const reference = randomUUID();
+        const result = await this.call('join', [name, options, reference], control);
+        return { ...result, participant: this.participantHandle(result.participant, reference) };
     }
     history(...[query, control]) { return this.call('history', [query], control); }
     status(...[options, control]) { return this.call('status', [options], control); }

package/dist/square-tools.d.ts

@@ -16,7 +16,7 @@ interface ToolDefinition {
 export interface ToolControl extends OperationControl {
     readonly observe?: boolean;
 }
-export declare const SQUARE_TOOL_INSTRUCTIONS = "Join once. Then express to speak, and catch to take in what reached you. History looks back without taking anything in.";
+export declare const SQUARE_TOOL_INSTRUCTIONS = "The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.";
 export declare const SQUARE_TOOLS: readonly ToolDefinition[];
 export declare function squareToolFailure(error: unknown, signal?: AbortSignal): JsonObject;
 /** Readable failure text with the same recovery commands the CLI offers, never raw JSON. */

package/dist/square-tools.js

@@ -1,9 +1,9 @@
 import { z } from 'zod/v4';
 import { isSquareError } from './model.js';
 import { CATCH_DEFAULT_LIMIT } from './square-api.js';
-import { renderCatchOutcome, renderExpression, renderFailureLines, renderHistoryResult, renderJoinResult, renderLifecycleResult, renderListenerChange, renderStatusResult, } from './operation-presentation.js';
-const location = z.string().optional().describe('Which square: a .square file path, or a backend URI like stdio://name/key. Relative paths start from the working directory. Leave it out for the configured square.');
-const participant = z.string().optional().describe('Your name in the square. Leave it out if you hold exactly one name here.');
+import { renderCatchOutcome, renderExpression, renderFailureLines, renderHistoryResult, renderJoinResult, renderLifecycleResult, renderListenerChange, renderListeningResult, renderParticipantsResult, renderStatusResult, } from './operation-presentation.js';
+const location = z.string().optional().describe('Local .square artifact path or configured backend URI (stdio://name/key). Relative paths use the current working directory. Defaults to the configured square.');
+const participant = z.string().optional().describe('Participant name. Defaults to the configured participant or the current session’s unambiguous participant.');
 const activityId = z.string().regex(/^act\/(0|[1-9][0-9]*)$/);
 const stringArray = z.array(z.string());
 /** Keep the observation request internal: it is not an argument a caller decides. */
@@ -48,69 +48,43 @@ function tool(name, description, shape, run, render) {
             return filtered;
         } };
 }
-export const SQUARE_TOOL_INSTRUCTIONS = 'Join once. Then express to speak, and catch to take in what reached you. History looks back without taking anything in.';
-const target = z.string().describe('The participant to turn toward or away from.');
+export const SQUARE_TOOL_INSTRUCTIONS = 'The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.';
 export const SQUARE_TOOLS = [
-    tool('join', 'Step into the square under your name. Do this once before you speak or catch. You arrive seeing what was said most recently.', {
-        as: z.string().optional().describe('Your name in the square. Give it explicitly when joining.'), takeover: z.boolean().optional().describe('Claim this name even though another session holds it now. That session loses it.'),
-    }, async (square, { as, takeover }, control) => {
+    tool('join', 'Join the square as a participant.', { as: participant, takeover: z.boolean().optional().describe('Take the name from its current session owner.') }, async (square, { as, takeover }, control) => {
         const { participant, ...receipt } = await square.join(as, { takeover, ...observation(control) }, control);
         return { ...receipt, participant: participant.name };
     }, rendering((result) => renderJoinResult(result))),
-    tool('express', 'Speak or act in the square. Plain words, half-formed ideas and *actions* all belong here. Mention or reply to someone to be heard by them; ring the bell to be heard by everyone. Said to no one in particular, your words reach those who listen to you.', {
-        as: participant,
-        body: z.string().describe('What you say or do. Markdown works; *asterisks* mark an action.'),
-        mentions: stringArray.optional().describe('Who you are speaking to. An @name in the body that matches someone here counts too.'),
-        reach: z.enum(['bell']).optional().describe('"bell" calls everyone in the square. Cannot be used with mentions.'),
-        reply: activityId.optional().describe('The activity you are answering, like act/12. Its author hears you if still here.'),
-        noMention: z.boolean().optional().describe('Leave @names in the body as plain text. Mentions and reply still reach people.'),
-        force: z.boolean().optional().describe('Speak now, even if something reached you that you have not caught yet.'),
-        noWait: z.boolean().optional().describe('If a hand is raised or you are speaking too fast, return at once instead of waiting.'),
+    tool('express', 'Express a message or embodied action in the square. Mentions and replies direct attention; bell reaches everyone and keeps body @names literal. Bell cannot combine with explicit mentions. Bare activity is valid even with no listeners.', {
+        as: participant, body: z.string(), mentions: stringArray.optional(), reach: z.enum(['bell']).optional(),
+        reply: activityId.optional(), noMention: z.boolean().optional().describe('Disable body @name scanning; explicit mentions and reply still apply.'),
+        force: z.boolean().optional().describe('Speak without first catching unread activity or satisfying attention etiquette.'),
+        noWait: z.boolean().optional().describe('Return an error rather than waiting when held or throttled.'),
     }, async (square, { body, as, ...options }, control) => {
         const { delivery: _delivery, ...result } = await (await square.participant(as)).express(body, { ...options, ...observation(control) }, control);
         return result;
     }, rendering((result) => renderExpression(result.observation?.location ?? '', result))),
-    tool('catch', 'Take in what reached you since you last looked: mentions, replies, bells, and words from those you listen to. What you catch no longer waits for you; history lets you look back.', {
-        as: participant,
-        id: activityId.optional().describe('Take in this activity in full, like act/12, even if you caught it before. Do not combine with idle, from, mention or limit.'),
-        idle: z.number().finite().min(0).optional().describe('When nothing is waiting, wait until something arrives or until it has been quiet this many milliseconds. Leave it out to return at once.'),
-        from: stringArray.optional().describe('Only what these participants said.'),
-        mention: z.boolean().optional().describe('Only what was addressed to you, and bells.'),
-        limit: z.number().int().min(1).optional().describe('At most this many at once (default 10, up to 100). The rest keeps waiting.'),
+    tool('catch', 'Catch and consume activities perceptible to the participant. idle waits for relevant activity or this many milliseconds of quiet; omitted means immediate. id catches one activity and cannot be combined with filters, idle or limit.', {
+        as: participant, id: activityId.optional(), idle: z.number().finite().min(0).optional(), from: stringArray.optional(),
+        mention: z.boolean().optional(), limit: z.number().int().min(1).optional(),
     }, async (square, { as, ...options }, control) => (await square.participant(as)).catch({ ...options, ...observation(control) }, control), rendering((result, args) => {
         // The CLI always spells the default cap in its continuation, so the tool does too.
         const options = args;
         const renderOptions = options.id === undefined ? { ...options, limit: options.limit ?? CATCH_DEFAULT_LIMIT } : options;
         return renderCatchOutcome(result.observation?.location ?? '', result, renderOptions).stdout;
     })),
-    tool('history', 'Look back at what was said. Reading here takes nothing in: whatever waits for catch keeps waiting. Page with before or after.', {
-        limit: z.number().int().min(1).optional().describe('How many per page (default 10, up to 100).'),
-        order: z.enum(['asc', 'desc']).optional().describe('"asc" for oldest first (default), "desc" for newest first.'),
-        before: activityId.optional().describe('The page just before this activity, like act/12.'),
-        after: activityId.optional().describe('The page just after this activity, like act/12.'),
-        grep: z.string().optional().describe('Only activities matching this regular expression in their names, ids or words. Use grep or fixed, not both.'),
-        fixed: z.string().optional().describe('Only activities containing this exact text.'),
-        from: stringArray.optional().describe('Only what these participants said.'),
-        mention: z.string().optional().describe('Only what was addressed to this participant.'),
+    tool('history', 'Read the activity stream without consuming it, using stable activity-id cursors. Default page size is 10, maximum 100. grep is a regex; fixed is literal text; use only one.', {
+        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(),
     }, (square, args, control) => square.history({ ...args, ...observation(control) }, control), rendering((result, args) => renderHistoryResult(result.observation?.location ?? '', result, { query: args }))),
-    tool('attention', 'Turn toward someone or away from them, from now on. Listen: hear everything they say, even to others. Unlisten: stop listening without clearing an ignore; mentions and replies still reach you unless ignored. Ignore: hear nothing from them but bells. What was already said stays as it was.', {
-        as: participant, action: z.enum(['listen', 'unlisten', 'ignore']).describe('"listen", "unlisten" or "ignore". Listening again ends an ignore.'), target,
-    }, async (square, { as, action, target }, control) => {
-        const self = await square.participant(as);
-        return self[action](target, observation(control), control);
-    }, rendering((result, args) => renderListenerChange(result.observation?.location ?? '', args.action, result))),
-    tool('hold', 'Raise a hand to pause the conversation; lower it with release. While a hand is up, new words wait to land.', {
-        as: participant,
-        reason: z.string().optional().describe('Why you are pausing. Everyone sees it.'),
-        release: z.boolean().optional().describe('true lowers the raised hand so the conversation goes on.'),
-    }, async (square, { as, reason, release }, control) => {
-        const self = await square.participant(as);
-        return release === true ? self.resume(observation(control), control) : self.hold(reason, observation(control), control);
-    }, rendering((result, args) => renderLifecycleResult(result.observation?.location ?? '', args.release === true ? 'resume' : 'hold', result))),
-    tool('done', 'Step out of the square. Everyone sees you leave, and you stop listening to anyone. Leaving carries no words, so say goodbye with express first. Stay instead if someone may still need you; you can join again later.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).done(undefined, observation(control), control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', 'done', result))),
-    tool('status', 'Look around the square: who is here, whether a hand is raised, the latest activity, and who you listen to.', {
-        as: z.string().optional().describe('Whose listening to show. Leave it out if you hold exactly one name here.'),
-    }, (square, { as }, control) => square.status({ viewer: as, ...observation(control) }, control), rendering((result) => renderStatusResult(result.observation?.location ?? '', result))),
+    tool('listen', 'Listen for future activity from a participant, clearing any ignore of them.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).listen(target, observation(control), control), rendering((result) => renderListenerChange(result.observation?.location ?? '', 'listen', result))),
+    tool('ignore', 'Block a participant’s future mentions and bare activity. Listening again clears the ignore; already landed activity is unchanged.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).ignore(target, observation(control), control), rendering((result) => renderListenerChange(result.observation?.location ?? '', 'ignore', result))),
+    tool('unlisten', 'Stop listening to a participant’s future activity; mentions and replies still reach you. An existing ignore is unchanged.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).unlisten(target, observation(control), control), rendering((result) => renderListenerChange(result.observation?.location ?? '', 'unlisten', result))),
+    tool('listening', 'List participants this participant is listening to.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).listening(observation(control), control), rendering((result) => renderListeningResult(result.observation?.location ?? '', result))),
+    tool('hold', 'Raise a hand to hold the square.', { as: participant, reason: z.string().optional() }, async (square, { as, reason }, control) => (await square.participant(as)).hold(reason, observation(control), control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', 'hold', result))),
+    tool('resume', 'Release the current hold.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).resume(observation(control), control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', 'resume', result))),
+    tool('done', 'Leave the square without adding a message.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).done(undefined, observation(control), control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', 'done', result))),
+    tool('status', 'Read the public status of the square.', {}, (square, _args, control) => square.status(observation(control), control), rendering((result) => renderStatusResult(result.observation?.location ?? '', result))),
+    tool('participants', 'List participants standing in or done with the square.', {}, (square, _args, control) => square.participants(observation(control), control), rendering((result) => renderParticipantsResult(result.observation?.location ?? '', result))),
 ];
 export function squareToolFailure(error, signal) {
     const normalized = signal?.aborted

package/dist/stdio-server.js

@@ -16,6 +16,13 @@ export async function runSquareStdioServer(root) {
     let square;
     let location;
     let opening = false, closing = false;
+    const participants = new Map();
+    const captureParticipant = (reference, participant) => {
+        if (typeof reference !== 'string' || reference.length === 0 || participants.has(reference))
+            throw new SquareError('invalid_args', 'Participant handle must be a fresh connection-local reference');
+        participants.set(reference, participant);
+        return participant.name;
+    };
     const running = new Map();
     const write = (message) => { if (!process.stdout.destroyed)
         process.stdout.write(JSON.stringify(message) + '\n'); };
@@ -91,10 +98,12 @@ export async function runSquareStdioServer(root) {
         const args = params.args.map((arg) => arg === null ? undefined : arg);
         let result;
         switch (method) {
-            case 'participant': return (await square.participant(args[0])).name;
+            case 'participant': return captureParticipant(args[1], await square.participant(args[0]));
             case 'join': {
+                if (typeof args[2] !== 'string' || args[2].length === 0 || participants.has(args[2]))
+                    throw new SquareError('invalid_args', 'Participant handle must be a fresh connection-local reference');
                 const joined = await square.join(args[0], args[1], control);
-                result = { ...joined, participant: joined.participant.name };
+                result = { ...joined, participant: captureParticipant(args[2], joined.participant) };
                 break;
             }
             case 'history':
@@ -112,8 +121,19 @@ export async function runSquareStdioServer(root) {
             default: {
                 if (typeof params.participant !== 'string')
                     throw new SquareError('invalid_args', 'Participant operation requires a name');
-                const participant = await square.participant(params.participant);
+                const participant = participants.get(params.participantHandle);
+                if (participant === undefined || participant.name !== params.participant)
+                    throw new SquareError('invalid_args', 'Select a captured participant handle on this connection');
                 switch (method) {
+                    case 'deferDelivery':
+                        result = await participant.deferDelivery(args[0], control);
+                        break;
+                    case 'renewDeliveryDeferral':
+                        result = await participant.renewDeliveryDeferral(args[0], args[1], control);
+                        break;
+                    case 'releaseDeliveryDeferral':
+                        result = await participant.releaseDeliveryDeferral(args[0], control);
+                        break;
                     case 'express':
                         result = await participant.express(args[0], args[1], control);
                         break;

package/dist/views.js

@@ -158,7 +158,6 @@ export function listPresentation(facts) {
 export function queryStatus(facts, context, viewer = '', observe = false) {
     const participants = coreParticipants(facts, context.now);
     const header = facts.header(), hold = facts.hold(), standingCount = inSquareCount(facts);
-    const listener = participants.find((p) => p.state !== 'not joined' && nameKey(p.name) === nameKey(viewer));
     const latest = facts.activityHeads({ kinds: ['say', 'done'] }, { edge: 'newest', limit: 1 }).items[0];
     const latestAct = latest === undefined ? undefined : facts.activity(latest.index);
     const data = {
@@ -170,7 +169,6 @@ export function queryStatus(facts, context, viewer = '', observe = false) {
             ...(hold.reason === undefined ? {} : { reason: hold.reason }),
             ...(hold.at === undefined ? {} : { at: hold.at }),
         } : null,
-        ...(listener === undefined ? {} : { listening: listener.listening }),
         participants: participants.filter((p) => p.state !== 'not joined'), now: context.now,
         ...(latestAct === undefined || latestAct.actor === undefined || latestAct.kind === 'read' ? {} : { latestActivity: toPublicActivity(latestAct) }),
     };

package/guides/backends.md

@@ -55,9 +55,10 @@ import { Square, type SquareBackends } from '@astrosheep/square';
 const backends: SquareBackends = {
   local: { command: process.execPath, args: ['/absolute/path/to/square/dist/stdio-server.js', '--root', '/tmp/squares'] },
 };
-const square = await Square.at({ path: 'stdio://local/design', backends, participant: 'Bob' });
+const square = await Square.at({ path: 'stdio://local/design', backends, participant: 'Bob',
+  body: { channel: 'example', session: 'bob-process' } });
 try {
-  const bob = (await square.join()).participant;
+  const bob = (await square.join('Bob')).participant;
   const caught = await bob.catch();
   console.log(caught.activities);
 } finally {
@@ -99,7 +100,7 @@ configured local SQLite connection. Pi tools accept the identical location and r
 - CLI failed-expression drafts stay in local `./drafts` for backend locations; recovery commands and
   display labels retain the URI. Local-artifact draft placement is unchanged.
 
-## Protocol version 1
+## Protocol version 2
 
 Newline-delimited JSON-RPC 2.0 over UTF-8 stdin/stdout, one object per line, at most 8 MiB per frame.
 Stdout is protocol only. No batch requests. The initial versioned handshake opens one logical square
@@ -107,9 +108,9 @@ per connection and returns an opaque handle. IDs are unique positive integers on
 requests may overlap and responses may arrive out of order.
 
 ```json
-{"jsonrpc":"2.0","id":1,"method":"square/open","params":{"version":1,"key":"design","location":"stdio://local/design","identity":{"PI_SESSION_ID":"session-id"},"participant":"Bob"}}
-{"jsonrpc":"2.0","id":1,"result":{"version":1,"handle":"square"}}
-{"jsonrpc":"2.0","id":2,"method":"join","params":{"handle":"square","args":["Bob",{"observe":true}]}}
+{"jsonrpc":"2.0","id":1,"method":"square/open","params":{"version":2,"key":"design","location":"stdio://local/design","identity":{"PI_SESSION_ID":"session-id"},"body":{"channel":"pi","session":"session-id"},"participant":"Bob"}}
+{"jsonrpc":"2.0","id":1,"result":{"version":2,"handle":"square"}}
+{"jsonrpc":"2.0","id":2,"method":"join","params":{"handle":"square","args":["Bob",{"observe":true},"fresh-participant-reference"]}}
 ```
 
 Open may include `build: {markdown, hardCap?, throttlePerMinute?, template?, force?}` instead of
@@ -120,25 +121,36 @@ coordinates (including PASEO_AGENT_ID), then overlays explicit call-local facts
 `process.env`. Participant defaults remain separate from square keys. Each new tool open therefore
 uses that call's identity, not MCP/Pi/backend startup identity.
 
-After open, methods take `{handle, args, participant?}`. `args` is the public operation's positional
-arguments excluding `OperationControl`; trailing JSON nulls represent omitted optional arguments.
+After open, square methods take `{handle, args}` and Participant methods additionally require
+`{participant, participantHandle}`. Selection/join supply a fresh opaque connection-local reference;
+the server retains the actual captured Participant under it instead of reselecting by name per
+request. Version 2 deliberately refuses older peers rather than accepting unfenced handles.
+`args` is the public operation's positional arguments excluding `OperationControl`, plus the
+selection reference noted below; trailing JSON nulls represent omitted optional arguments.
 Nested nulls such as `history({limit:null})` retain their public meaning.
 
 | Methods | args | participant field |
 | --- | --- | --- |
-| `participant` | `[name?]` | no; selection only, not joining |
-| `join` | `[name?, options?]` | no |
+| `participant` | `[name?, freshReference]` | no; selection only, not joining |
+| `join` | `[name, options?, freshReference]` | no |
 | `history`, `status`, `participants` | `[options?]` | no |
 | `recovery` | `[name?]` | no |
 | `express` | `[body, options?]` | required |
 | `catch`, `listening`, `resume` | `[options?]` | required |
 | `listen`, `ignore`, `unlisten` | `[target, options?]` | required |
 | `hold`, `done` | `[body?, options?]` | required |
+| `deferDelivery` | `[{match, durationMs}]` | required |
+| `renewDeliveryDeferral` | `[id, durationMs]` | required |
+| `releaseDeliveryDeferral` | `[id]` | required |
 
 Results are the concrete public operation results, including requested observations. Participant
 handles serialize as names for `participant` and `join.participant` and become real local handles
-on the client. Observation locations are canonical remote URIs and automatic delivery is false.
-Errors are JSON-RPC `{code:-32000,message,data:{code?,facts?,operation?}}`; Square codes, structured
+on the client, using their retained connection-local references. Done/takeover/rejoin fences old
+references even when the same Body later reacquires the name. Observation locations are canonical
+remote URIs and automatic delivery is false. SDK/stdio deferrals have identical validation, independent
+lease and owner-generation semantics; create/renew return only `{id, expiresAt}`, renew returns null
+and release false for an inactive ID, and stale handles receive the normal ownership refusal.
+No CLI/MCP/Pi deferral-authoring command is included. Errors are JSON-RPC `{code:-32000,message,data:{code?,facts?,operation?}}`; Square codes, structured
 facts, history bounds and express certainty survive the boundary. The client does not infer
 `unsent` from a connection failure. There is no mutation retry or replay.
 
@@ -147,7 +159,8 @@ Progress is a notification
 `OperationProgress`. Request abort sends `$/cancelRequest` with `{id}`; the server aborts only that
 request and returns its response **after** cleanup, including releasing a catch lease. Another
 request on the same handle continues normally. Cancellation never undoes an explicitly committed
-receipt. `square/close` with `{}` aborts/drains outstanding requests, closes SQLite and acknowledges
+receipt or lease mutation. A committed deferral remains until release, expiry or seat retirement;
+connection close does not cancel it. `square/close` with `{}` aborts/drains outstanding requests, closes SQLite and acknowledges
 with a null result. Client close is idempotent, waits briefly for graceful cleanup, then terminates
 an unresponsive process. EOF, malformed framing, version mismatch and process exit reject pending
 requests and release the connection. A lost express response after dispatch has unknown effect;

package/guides/change-waits.md

@@ -1,14 +1,40 @@
 # Waiting for changes
 
-Square's artifact and host-ledger adapters own change detection. Notifications are hints, not activity delivery or consumption receipts.
+Artifact revisions and the rebuildable discovery index drive change detection. Filesystem
+notifications are hints, not activity delivery or consumption receipts.
 
-- 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. Changed projections read typed recipient facts and selected bodies, not the whole 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. Host-ledger database metadata invalidates a process-shared read of its separate presence/evidence revisions; unchanged metadata requires no SQLite open. Revisions are read together in one short snapshot and cached against metadata captured before that read, so a concurrent mutation remains detectable. Failed reads are not cached. Missing ledger storage is stable until it appears. Neither metadata nor revisions are delivery evidence.
-- 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.
-- Existing catch filters, lease priority, presentation claims, full-delivery seen receipts, clipped previews, and session-local cancellation suppression remain in force. Sharing storage detection does not share session delivery state. Cancellation never creates a receipt or removes history.
+- 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 outstanding read.
+- Directory notifications invalidate lightweight reads. A two-second reconciliation checks revisions
+  even when notifications are missing. Missing directories, unsupported watches, watcher failures
+  and directory replacement retain that fallback. Latency is not a hard guarantee: a missed hint
+  may wait for reconciliation, scheduling and lock contention.
+- Conversation revision controls the pending-content cache. Delivery revision separately invalidates
+  eligibility, including delivery evidence, cancellation and deferral writes. Projections resolve
+  current typed seats and selected bodies in one coherent artifact read; they never grant authority
+  from an index entry or a cached eligibility decision. No sidecar, broker or second delivery store
+  is introduced. An unreadable candidate cannot authorize cached content.
+- Each active session pending observer subscribes before selecting current candidates and facts,
+  including when no seat is yet discoverable. Index publication can wake discovery without an
+  artifact write. A failed injection waits for substantive change; its own failed evidence write
+  does not cause a retry loop.
+- Deferral create/renew/release and opportunistic pruning change delivery revision, not conversation
+  activity. Release rechecks eligibility without a new message. Expiry needs no synthetic write:
+  the observer includes the earliest relevant matching live deferral expiry in its existing wait
+  deadline, alongside catch-lease expiry/staleness. Overlapping leases remain OR; an early expiry
+  rechecks the remaining live leases. Renewal changes that deadline without self-triggered delivery.
+- There is no new daemon or detached per-message timer. A one-shot producer skips deferred work and
+  returns promptly. An existing active delivery observer will reconsider release/expiry; absent an
+  observer, pending work waits for the next normal delivery opportunity. A lease does not create a
+  process that was not already running.
+- Blocking catch waits for conversation revision or its heartbeat/quiet deadline. A held catch keeps
+  its single lease alive and pauses quiet expiry. Core catch and streams use the same storage change
+  detector. Held express also waits for changes; throttling waits for its eligibility time.
+- Deferrals are independent of catch filters, presentation claims, full-delivery seen receipts,
+  clipped previews and session-local cancellation. Sharing storage detection does not share session
+  delivery state. Cancellation never creates a receipt or removes archive history. A deferral cannot
+  recall a send already past its final freshness check.
 
 ## Verification
 
@@ -23,6 +49,9 @@ node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 30
 node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 300 --mode session --active --no-hints
 ```
 
-The benchmark creates disposable synthetic history. poll200 measures 200ms revision polling; events measures revision waits. session includes binding and notification projection, but excludes initial setup. Active session runs compare 1,800 and 18,000 unrelated history rows, inject one bell without push, then catch concurrently. `--no-hints` disables filesystem hints only inside benchmark workers. Runs report committed-write-to-projection latency, not native Pi message landing, and retain the twenty-second discovery deadline as a probe bound rather than an SLA. Three hundred processes still have three hundred monitors: sharing is process-local, not cross-process deduplication. See [row runtime delivery evidence](row-runtime-delivery-evidence.md) for actual completion, hydration, CPU, lock contention and host-ledger costs.
-
-A long-running Pi process must reload/restart its Square extension to use rebuilt code.
+The benchmark creates disposable synthetic history. Process-local sharing does not deduplicate
+monitors across processes. Timings measure committed-write-to-projection latency, not native
+message landing, and discovery deadlines are probe bounds rather than an SLA. Historical benchmark
+evidence may describe older HostLedger implementations; it is not current custody authority.
+A long-running extension must reload upgraded code before using the new artifact format; this
+delivery does not install or restart one.

package/guides/claude-native.md

@@ -21,14 +21,14 @@ An absent/broken endpoint is unavailable; it does not consume Square activity.
 
 ## Native-first routing and policy holds
 
-Native delivery is preferred, including under Paseo. CLI and call-local MCP Codex
-joins register the native queue for their thread. Claude and OpenCode receivers
-register their native wake addresses only through their loaded integrations. An
-ordinary reconnect or implicit join cannot replace a current native address with a
-generic Paseo proposal. Addresses belong to the artifact seat generation, not an
-expiring routes table: explicit receiver withdrawal permits fallback, and a new
-seat generation cannot inherit the previous generation's native registration.
-Participant expressions do not publish replacement addresses.
+Native delivery is preferred, including under Paseo. Codex proposes its capable
+native queue before Paseo. Claude and OpenCode receivers register their native
+routes only through their loaded integrations. The common publication transaction
+keeps a fresh native registration ahead of a Paseo proposal for the same
+participant, session, channel and ownership epoch. Tool operations cannot flip it
+back to Paseo between receiver reconciliations. An absent, expired or explicitly
+retired native registration does not block a Paseo fallback; a replacement epoch
+cannot inherit an older native registration.
 
 This is route preference, not permission to bypass receiver policy. Claude can
 legitimately hold an unsolicited peer message with `no-mode-asserted`, especially
@@ -47,7 +47,7 @@ Neither a release nor a drop is a queue receipt, proof of consumption or retry
 authorization.
 
 `square harness doctor delivery` shows native custody separately from pending
-attention for current seat generations, including after the activity is seen. Paseo
+attention, including after the activity is seen or the participant leaves. Paseo
 presents the `peer_message_hold` state in its own timeline. Acceptance means normal
 delivery when the receiver allows it, or a visible reason without bypass/replay when
 policy holds it.

package/guides/mcp.md

@@ -4,7 +4,7 @@ Square provides a stdio MCP server through `square mcp-server`.
 
 Set `SQUARE_LOCATION` to the default `.square` artifact path; calls may override it with `location`. Relative paths use the server's startup working directory. Join with an explicit `as` name. Later calls may omit `as` only when the artifact recognizes exactly one current name held by the call's exact Body (`channel`, `session`, optional `agent`); zero or multiple matches refuse and require explicit selection. An explicit name selects a voice but never grants custody. Request metadata supplies the live Codex (`threadId`) or OpenCode (`ai.opencode/sessionID`) coordinate when present; otherwise a reliable startup coordinate is required for participant writes. Read-only calls do not need a Body.
 
-The server exposes `join`, `express`, `catch`, `history`, `attention`, `hold`, `done`, and `status`. `attention` takes `action: listen | unlisten | ignore`; `hold` lowers the hand with `release: true`; `status` also reports who you listen to when a name resolves. `catch` consumes activities. `history` is read-only and accepts stable `act/<index>` cursors. Tool results include JSON `structuredContent` and a text representation of the same data. Square failures are returned as tool errors with a structured `{ error: { code, message, facts? } }` value.
+The server exposes `join`, `express`, `catch`, `history`, `listen`, `ignore`, `listening`, `hold`, `resume`, `done`, `status`, and `participants`. `catch` consumes activities. `history` is read-only and accepts stable `act/<index>` cursors. Tool results include JSON `structuredContent` and a text representation of the same data. Square failures are returned as tool errors with a structured `{ error: { code, message, facts? } }` value.
 
 Claude's bundled plugin configures this server automatically. Its mod supplies live session/cwd/subagent attribution through an out-of-band tool-use-ID association, not AI-visible arguments; see [Claude call identity](claude-native.md#mcp-tools-and-call-identity). The bundled endpoint requires that association rather than falling back to its startup environment.
 

package/guides/migration.md

@@ -2,8 +2,9 @@
 
 Square stores its authority in one versioned SQLite artifact. Format 1 kept the
 history as one JSON snapshot; format 2 introduced typed rows; format 3 added the
-`unlisten` activity; format 4 adds artifact-owned participant seats and delivery
-evidence. Existing artifacts are never converted implicitly.
+`unlisten` activity; format 4 added artifact-owned participant seats and delivery
+evidence; format 5 adds independent expiring delivery deferrals. Existing artifacts are never
+converted implicitly.
 
 Use the explicit command while all processes using the artifact are stopped:
 
@@ -11,11 +12,24 @@ Use the explicit command while all processes using the artifact are stopped:
 square --location /path/to/SQUARE.square migrate
 ```
 
-The command handles the supported older formats in place. It does not create a
+The command handles supported formats 2, 3 and 4 in place and publishes only final format 5.
+It does not create a
 backup, stop processes, install a runtime, or update another artifact. A legacy
 HostLedger that needs its own format conversion must be prepared separately with
 the old runtime's offline tooling.
 
+## Format 4 additive conversion
+
+An exact format-4 artifact needs no legacy owner or route import: that authority already lives
+inside the artifact. Read-only preflight checks framing and stored facts. One SQLite transaction
+adds the empty `delivery_deferrals` table and its owner/generation/expiry lookup index, then
+publishes format 5. The dedicated table stores participant key, captured generation, opaque ID,
+validated match and expiry, separately from catch leases and delivery evidence. All existing
+activities (including metadata), audience, receipts, seats, catch leases, delivery evidence,
+cancellation boundaries and both revision values remain unchanged. No lease is manufactured.
+The conversion does not consult or mutate HostLedger. Failure rolls back the table, index and
+format marker together.
+
 ## Format 3 preflight and conversion
 
 Before writing, migration validates the exact format-3 schema, header, and legacy
@@ -54,8 +68,8 @@ ledger is read-only and remains untouched, so it is still available for offline
 diagnostics. An absent ledger cannot establish standing ownership; an unreadable
 or unsupported ledger refuses before changing the square.
 
-After successful preflight, one SQLite transaction creates format-4 ownership and
-evidence rows and publishes the format marker. Activity history and indices,
+After successful preflight, one SQLite transaction creates ownership/evidence rows and the
+empty deferral table/index, then publishes format 5. Activity history and indices,
 receipts, lease contents, and the artifact revision are preserved. Legacy routes
 are decoded only during migration and their table is removed. Existing lease
 generations are resolved only for exact owner spellings that match a standing
@@ -65,12 +79,13 @@ format, and any failure before commit rolls back the conversion.
 
 Format 2 first rebuilds only the activity table and its indexes to accept
 `unlisten`, then follows the same row-format preflight and conversion. Snapshot
-format 1 is not accepted by this format-4 migration.
+format 1 is not accepted by this migration. Formats 2/3 never publish an intermediate format 4.
 
 ## What migration refuses
 
-Migration validates the exact old row schema, including the legacy routes table,
-using migration-local codecs. Current format 4 has no routes table or runtime route
+Migration validates each source's exact row schema. Formats 2/3 include the legacy routes table,
+read using migration-local codecs; format 4 already has seats and delivery evidence. Current
+format 5 has no routes table or runtime route
 reader; migration consumes the old rows only to resolve seats, then drops the legacy
 table as part of the format change.
 
@@ -99,8 +114,8 @@ remains a byte-preserving no-op.
 
 ## Before and after migration
 
-Stop every session or service using the square and any process writing its
-HostLedger. Make an offline backup, or use SQLite's backup facilities rather than
+Stop every session or service using the square, and for formats 2/3 freeze any process writing its
+legacy HostLedger. Make an offline backup, or use SQLite's backup facilities rather than
 copying a live database. Migration does not revoke an in-flight remote delivery or
 modify HostLedger evidence. Square writes use ordinary SQLite `DELETE` journals:
 the artifact must be writable and its containing directory must permit journal
@@ -109,7 +124,10 @@ participation and delivery authority live in the artifact, not writable HOME;
 loss of the rebuildable HOME discovery index may limit automatic discovery but
 does not transfer custody or erase durable delivery evidence.
 
-Upgrade attached runtimes before reopening the format-4 artifact; older runtimes
-must not be mixed with it. Run the read-only `doctor` command after migration and
+Upgrade all attached runtimes before reopening the format-5 artifact; older runtimes
+must not be mixed with it. Updating a package does not migrate an artifact, and migrating an
+artifact does not install upgraded runtimes. For rollback after a committed conversion, stop all
+clients and restore the offline backup with its compatible older runtime; do not downgrade the
+format marker or drop tables in place. Run the read-only `doctor` command after migration and
 before restarting clients. Repeating migration on a current artifact is a
 byte-preserving no-op.