@astrosheep/square 0.4.6 → 0.4.8

package/dist/square-tools.js

@@ -1,94 +1,32 @@
-import crypto from 'node:crypto';
 import { z } from 'zod/v4';
 import { isSquareError, SquareError } from './model.js';
-import { requireOwner, requireJoinName, selectOwnSeat, PERCEIVE_DEFAULT_LIMIT, DEFAULT_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_DEPTH, MAX_LIST_LIMIT } from './square-api.js';
+import { requireOwner, requireJoinName, selectOwnSeat, HISTORY_MAX_LIMIT, PERCEIVE_MAX_LIMIT, PERCEIVE_DEFAULT_LIMIT, DEFAULT_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_DEPTH, MAX_LIST_LIMIT } from './square-api.js';
+import { parseDurationMs, parseTimeOrRelative } from './time.js';
 import { renderPerceiveOutcome, renderExpression, renderFailureLines, renderHistoryResult, renderJoinResult, renderLifecycleResult, renderListenerChange, renderStatusResult, renderSquareList, } from './operation-presentation.js';
-/** Process-local recovery: FIFO 64, fixed two-hour TTL, consumed only by a successful express. */
-const EXPRESS_DRAFT_TTL_MS = 2 * 60 * 60 * 1000;
-const EXPRESS_DRAFT_LIMIT = 64;
-export class SquareExpressDrafts {
-    drafts = new Map();
-    purgeExpired() {
-        const now = Date.now();
-        for (const [token, draft] of this.drafts)
-            if (draft.expiresAt <= now)
-                this.drafts.delete(token);
-    }
-    resolve(args, owner) {
-        if (args.draft === undefined)
-            return { args };
-        this.purgeExpired();
-        if (typeof args.draft !== 'string' || Object.keys(args).length !== 1)
-            throw new SquareError('invalid_args', 'An express draft token cannot be combined with other arguments.');
-        const draft = this.drafts.get(args.draft);
-        if (draft === undefined || draft.owner !== owner)
-            throw new SquareError('invalid_args', 'Unknown, expired, or inaccessible express draft.');
-        return { args: draft.args, token: args.draft };
-    }
-    consume(token) {
-        if (token !== undefined)
-            this.drafts.delete(token);
-    }
-    retain(args, owner, token, failure, expressAttempted) {
-        const effect = failure.operation?.expressEffect;
-        // After an attempt, only an admission or argument refusal proves that retrying cannot duplicate an activity.
-        const unsent = !expressAttempted || effect === 'unsent' || (effect === undefined && failure.code === 'invalid_args');
-        if (!unsent || effect === 'landed' || effect === 'unknown' || typeof args.body !== 'string' || args.draft !== undefined
-            || typeof args.location !== 'string' || !args.location.trim())
-            return undefined;
-        this.purgeExpired();
-        if (token !== undefined && this.drafts.has(token))
-            return token;
-        const created = `dr_${crypto.randomBytes(16).toString('base64url')}`;
-        this.drafts.set(created, { owner, args, expiresAt: Date.now() + EXPRESS_DRAFT_TTL_MS });
-        if (this.drafts.size > EXPRESS_DRAFT_LIMIT)
-            this.drafts.delete(this.drafts.keys().next().value);
-        return created;
-    }
-}
 export function createSquareToolRunner() {
-    const drafts = new SquareExpressDrafts();
     return async (tool, args, control, bind) => {
-        let toolArgs = args;
-        let owner;
-        let token;
-        let attempted = false;
         let square;
         try {
             const binding = await bind();
-            owner = binding.identity.owner;
             if ('runDiscovery' in tool)
-                return { text: await tool.runDiscovery(toolArgs, control, binding) };
-            if (tool.name === 'express') {
-                const resolved = drafts.resolve(toolArgs, owner);
-                toolArgs = resolved.args;
-                token = resolved.token;
-            }
-            square = await binding.open(toolArgs.location, control);
-            let text;
+                return { text: await tool.runDiscovery(args, control, binding) };
+            square = await binding.open(args.location, control);
             try {
-                attempted = tool.name === 'express';
-                text = await tool.run(square, toolArgs, control, binding.identity);
-                drafts.consume(token);
+                return { text: await tool.run(square, args, control, binding.identity, binding.now) };
             }
             finally {
                 await square.close();
             }
-            return { text };
         }
         catch (error) {
-            const failure = squareToolFailure(error, control.signal);
-            const draft = tool.name === 'express' ? drafts.retain(toolArgs, owner, token, failure, attempted) : undefined;
-            return { isError: true, text: squareToolFailureText(failure, {
-                    location: square?.location ?? toolArgs.location,
-                    participant: typeof toolArgs.as === 'string' ? toolArgs.as : undefined,
-                    draft,
+            return { isError: true, text: squareToolFailureText(squareToolFailure(error, control.signal), {
+                    location: square?.location ?? args.location,
+                    participant: typeof args.as === 'string' ? args.as : undefined,
                 }) };
         }
     };
 }
-const location = z.string().describe('Which square: a .square file path. Relative paths start from the working directory.');
-const expressLocation = z.string().optional().describe('Which square: a .square file path. Relative paths start from the working directory. Required unless retrying with a draft token.');
+const location = z.string().describe('Path to the .square file, relative to the working directory.');
 const participant = z.string().optional().describe('Your name in the square. Leave it out if you hold exactly one name here.');
 const activityId = z.string().regex(/^act\/(0|[1-9][0-9]*)$/);
 const stringArray = z.array(z.string());
@@ -97,11 +35,11 @@ function rendering(render) {
     return (result, args) => render(result, args);
 }
 function tool(name, description, shape, run, render) {
-    const inputSchema = z.object({ ...shape, location: name === 'express' ? expressLocation : location }).strict();
+    const inputSchema = z.object({ ...shape, location }).strict();
     return { name, description, inputSchema,
-        run: async (square, args, control, identity) => {
+        run: async (square, args, control, identity, now) => {
             const { location: _location, ...operationArgs } = inputSchema.parse(args);
-            const receipt = await run(square, operationArgs, control, identity);
+            const receipt = await run(square, operationArgs, control, identity, now);
             return render(receipt, operationArgs) ?? '';
         } };
 }
@@ -114,13 +52,15 @@ export function squareToolsEnabled(env = process.env) {
     throw new SquareError('invalid_args', 'Invalid SQUARE_TOOLS: expected 0, 1, true, false, or none.');
 }
 export const SQUARE_TOOL_INSTRUCTIONS = 'List nearby squares and your joined names with list. Pass location for a single square. Join once. Then express to speak, and perceive to take in what reached you. History looks back without taking anything in.';
-function historyToolQuery({ grep, fixed, before, after, ...query }) {
-    if (grep !== undefined && fixed !== undefined)
-        throw new SquareError('invalid_args', 'Use grep or fixed, not both.');
+function historyToolQuery({ search, regex, before, after, since, full: _full, ...query }, now = Date.now()) {
     if (before !== undefined && after !== undefined)
         throw new SquareError('invalid_args', 'Use before or after, not both.');
+    const sinceMs = since === undefined ? undefined : parseTimeOrRelative(since, now);
+    if (sinceMs !== undefined && !Number.isFinite(sinceMs))
+        throw new SquareError('invalid_args', `Invalid since timestamp: ${since}`);
     return { ...query,
-        search: grep !== undefined ? { text: grep, mode: 'regex' } : fixed === undefined ? undefined : { text: fixed, mode: 'literal' },
+        ...(sinceMs === undefined ? {} : { since: sinceMs }),
+        search: search === undefined ? undefined : { text: search, mode: regex ? 'regex' : 'literal' },
         cursor: after !== undefined ? { id: after, direction: 'after' } : before === undefined ? undefined : { id: before, direction: 'before' },
     };
 }
@@ -136,66 +76,69 @@ export const SQUARE_TOOLS = [
         inputSchema: listSchema,
         async runDiscovery(args, control, binding) {
             const options = listSchema.parse(args);
-            const { result, now } = await binding.discover({ ...options, owner: binding.identity.owner }, control);
-            return renderSquareList(result, { now, depth: options.depth ?? DEFAULT_LIST_DEPTH, limit: options.limit ?? DEFAULT_LIST_LIMIT });
+            const result = await binding.discover({ ...options, owner: binding.identity.owner }, control);
+            return renderSquareList(result, { now: (binding.now ?? Date.now)(), depth: options.depth ?? DEFAULT_LIST_DEPTH, limit: options.limit ?? DEFAULT_LIST_LIMIT, surface: 'tool' });
         },
     },
     tool('join', 'Step into the square under your name. Do this once before you speak or perceive. 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.'),
-    }, (square, { as, takeover }, control, identity) => square.join(requireJoinName(as), { ...identity, owner: requireOwner(identity.owner), takeover, observe: true }, control), rendering((result) => renderJoinResult(result))),
+        as: z.string().describe('Your name in the square.'),
+        takeover: z.boolean().optional().describe('Claim this name even though another session holds it now. That session loses it.'),
+        last: z.number().int().min(1).max(HISTORY_MAX_LIMIT).optional().describe('How many recent public activities to show on arrival (default 10).'),
+    }, (square, { as, takeover, last }, control, identity) => square.join(requireJoinName(as), { ...identity, owner: requireOwner(identity.owner), takeover, last, observe: true }, control), rendering((result) => renderJoinResult(result, undefined, 'tool'))),
     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().optional().describe('What you say or do. Markdown works; *asterisks* mark an action. Required unless retrying with a draft token.'),
-        draft: z.string().optional().describe('Retry a failed express kept in this process. Pass only the token; the original body and options are restored.'),
+        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.'),
+        bell: z.boolean().optional().describe('Call everyone in the square. Not 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 perceived yet.'),
         noWait: z.boolean().optional().describe('If you are speaking too fast, return at once instead of waiting.'),
-    }, async (square, { body, draft, as, ...options }, control, identity) => {
-        if (draft !== undefined)
-            throw new SquareError('invalid_args', 'Unknown or expired express draft.');
-        if (body === undefined)
-            throw new SquareError('invalid_args', 'Express needs a body or a draft token.');
-        return (await selectOwnSeat(square, identity.owner, as)).express(body, { ...options, observe: true }, control);
-    }, rendering((result) => renderExpression(result.observation?.location ?? '', result))),
+    }, async (square, { body, bell, as, ...options }, control, identity) => (await selectOwnSeat(square, identity.owner, as)).express(body, { ...options, ...(bell ? { reach: 'bell' } : {}), observe: true }, control), rendering((result) => renderExpression(result.observation?.location ?? '', result, undefined, 'tool'))),
     tool('perceive', 'Take in what reached you since you last looked: mentions, replies, bells, and words from those you listen to. What you perceive 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 perceived 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.'),
+        id: activityId.optional().describe('Open this one activity in full, like act/12. Use it alone.'),
+        idle: z.string().optional().describe('When nothing is waiting, wait for activity or this much quiet, like "30s". 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.'),
-    }, async (square, { as, ...options }, control, identity) => (await selectOwnSeat(square, identity.owner, as)).perceive({ ...options, observe: true }, control), rendering((result, args) => {
+        limit: z.number().int().min(1).max(PERCEIVE_MAX_LIMIT).optional().describe('At most this many at once (default 10). The rest keeps waiting.'),
+        takeover: z.boolean().optional().describe('Take over from another active idle perceive for this participant.'),
+    }, async (square, { as, idle, ...args }, control, identity) => {
+        const options = { ...args, ...(idle === undefined ? {} : { idle: parseDurationMs(idle, 'idle') }) };
+        return { ...(await (await selectOwnSeat(square, identity.owner, as)).perceive({ ...options, observe: true }, control)), options };
+    }, rendering((result) => {
         // The CLI always spells the default cap in its continuation, so the tool does too.
-        const options = args;
+        const options = result.options;
         const renderOptions = options.id === undefined ? { ...options, limit: options.limit ?? PERCEIVE_DEFAULT_LIMIT } : options;
-        return renderPerceiveOutcome(result.observation?.location ?? '', result, renderOptions).stdout;
+        return renderPerceiveOutcome(result.observation?.location ?? '', result, renderOptions, undefined, 'tool').stdout;
     })),
     tool('history', 'Look back at what was said. Reading here takes nothing in: whatever waits for perceive keeps waiting. Page with before or after.', {
-        limit: z.number().int().min(1).optional().describe('How many per page (default 10, up to 100).'),
+        limit: z.number().int().min(1).max(HISTORY_MAX_LIMIT).optional().describe('How many per page (default 10).'),
         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.'),
+        at: z.array(activityId).min(1).optional().describe('Center on these activity ids, like ["act/12"].'),
+        context: z.number().int().min(0).max(HISTORY_MAX_LIMIT).optional().describe('Activities of context before and after each "at" activity.'),
+        since: z.string().optional().describe('Only activities after this ISO timestamp or relative duration (like "10m").'),
+        search: z.string().optional().describe('Only activities containing this text in their names, ids or words.'),
+        regex: z.boolean().optional().describe('Treat search as a regular expression.'),
         from: stringArray.optional().describe('Only what these participants said.'),
         mention: z.string().optional().describe('Only what was addressed to this participant.'),
-    }, (square, args, control) => square.history({ ...historyToolQuery(args), observe: true }, control), rendering((result, args) => renderHistoryResult(result.observation?.location ?? '', result, { query: historyToolQuery(args) }))),
+        full: z.boolean().optional().describe('Show full activity bodies even when multiple activities are returned.'),
+    }, async (square, args, control, _identity, now) => {
+        const query = historyToolQuery(args, now?.());
+        return { ...(await square.history({ ...query, observe: true }, control)), query };
+    }, rendering((result, args) => renderHistoryResult(result.observation?.location ?? '', result, { query: result.query, full: args.full === true, surface: 'tool' }))),
     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, identity) => {
-        const self = await selectOwnSeat(square, identity.owner, as);
-        return self[action](target, { observe: true }, control);
-    }, rendering((result, args) => renderListenerChange(result.observation?.location ?? '', args.action, result))),
+    }, async (square, { as, action, target }, control, identity) => (await selectOwnSeat(square, identity.owner, as))[action](target, { observe: true }, control), rendering((result, args) => renderListenerChange(result.observation?.location ?? '', args.action, 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, identity) => (await selectOwnSeat(square, identity.owner, as)).done(undefined, { observe: true }, control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', result))),
     tool('status', 'Look around the square: who is here, 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.'),
     }, async (square, { as }, control, identity) => {
         const viewer = (await selectOwnSeat(square, identity.owner, as, { optional: true }))?.name;
         return square.status({ viewer, observe: true }, control);
-    }, rendering((result) => renderStatusResult(result.observation?.location ?? '', result))),
+    }, rendering((result) => renderStatusResult(result.observation?.location ?? '', result, { surface: 'tool' }))),
 ];
 export function squareToolFailure(error, signal) {
     const normalized = signal?.aborted
@@ -208,17 +151,7 @@ export function squareToolFailure(error, signal) {
     const operation = error instanceof Error ? error.operation : undefined;
     return operation === undefined ? normalized : { ...normalized, operation };
 }
-/** Readable failure text with the same recovery commands the CLI offers, never raw JSON. */
+/** Readable failure text with tool-native recovery actions, never raw JSON. */
 export function squareToolFailureText(failure, context = {}) {
-    const report = failure;
-    const lines = renderFailureLines(report, { squarePath: context.location, name: context.participant });
-    if (report.code === 'behind')
-        lines[0] = `✕ your words stay unsent — ${report.message}`;
-    if (context.draft !== undefined) {
-        lines.push(`· draft kept in memory: ${context.draft}`);
-        lines.push(report.code === 'behind'
-            ? '· perceive the pending activity, then retry express with only:'
-            : '· correct the problem above, then retry express with only:', `{ "draft": "${context.draft}" }`);
-    }
-    return lines.join('\n');
+    return renderFailureLines(failure, { squarePath: context.location, name: context.participant, surface: 'tool' }).join('\n');
 }

package/dist/square-values.d.ts

@@ -1,4 +1,4 @@
-export declare const WAKE_ROUTE_KINDS: readonly ["opencode-server", "codex-queue", "claude-native", "paseo", "http"];
+export declare const WAKE_ROUTE_KINDS: readonly ["opencode-server", "codex-queue", "paseo", "http"];
 export type WakeRouteKind = typeof WAKE_ROUTE_KINDS[number];
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;

package/dist/square-values.js

@@ -1,5 +1,5 @@
 import { SquareError, nameKey } from './neutral.js';
-export const WAKE_ROUTE_KINDS = ['opencode-server', 'codex-queue', 'claude-native', 'paseo', 'http'];
+export const WAKE_ROUTE_KINDS = ['opencode-server', 'codex-queue', 'paseo', 'http'];
 export const MESSAGE_METADATA_MAX_BYTES = 16 * 1024;
 export const MESSAGE_METADATA_MAX_DEPTH = 256;
 /** Validate the bounded, lossless JSON object carried by a message. */

package/dist/time.d.ts

@@ -1,3 +1,4 @@
+export declare function parseDurationMs(value: string, label: string): number;
 export declare function formatTimestamp(at: number): string;
 export declare function formatDuration(ms: number | undefined): string;
 export declare function formatRelativeTime(at: number, now?: number): string;

package/dist/time.js

@@ -1,3 +1,13 @@
+import { SquareError } from './model.js';
+export function parseDurationMs(value, label) {
+    const match = value.match(/^([1-9]\d*)(ms|s|m|h)$/);
+    if (!match)
+        throw new SquareError('invalid_args', `✕ invalid ${label}: expected a positive duration with unit ms, s, m, or h (for example 500ms, 30s, 3m, 1h)`);
+    const milliseconds = Number(match[1]) * ({ ms: 1, s: 1000, m: 60000, h: 3600000 }[match[2]]);
+    if (!Number.isSafeInteger(milliseconds))
+        throw new SquareError('invalid_args', `✕ invalid ${label}: duration is too large`);
+    return milliseconds;
+}
 function pad(value, length = 2) {
     return String(value).padStart(length, '0');
 }

package/dist/views.d.ts

@@ -19,7 +19,7 @@ export declare function selectHistory(facts: SquareRead, query: HistoryQuery, li
 export declare function publicActivities(activities: readonly ArchiveRecord[]): Activity[];
 export declare function recoveryObservation(facts: SquareRead, name: string, now: number): {
     participant: string;
-    activitySummaries: import("./square-facade.js").UnreadActivitySummary[];
+    activitySummaries: import("./neutral.js").UnreadActivitySummary[];
     standingCount: number;
     ownActivityCount: number;
     hardCap: import("./model.js").HardCap;

package/dist/views.js

@@ -35,14 +35,14 @@ export function parseRequiredActivityId(id) {
 }
 /** History adds archive context and ordering to the shared storage-side query predicates. */
 export function selectHistory(facts, query, limit, kinds, presentation = true) {
-    const shared = activityQueryFilter(query, ['observe', 'order', 'mention', 'since', 'contextBefore', 'contextAfter']);
+    const shared = activityQueryFilter(query, ['observe', 'order', 'mention', 'since', 'context']);
     const { afterIndex } = shared;
     const recipient = query.mention == null ? undefined : resolveKnownName(facts, query.mention);
     if (limit !== null && (!Number.isSafeInteger(limit) || limit < 1))
         throw new SquareError('invalid_args', 'History limit must be a positive integer');
     const filter = {
         ...shared, afterAt: query.since,
-        ...(shared.indexes === undefined ? {} : { indexes: facts.contextIndexes(shared.indexes, query.contextBefore ?? 0, query.contextAfter ?? 0) }),
+        ...(shared.indexes === undefined ? {} : { indexes: facts.contextIndexes(shared.indexes, query.context ?? 0, query.context ?? 0) }),
         kinds: query.search === undefined ? kinds : ['say', 'done'],
     };
     let selected, totalMatches, publicBefore = false, publicAfter = false;

package/dist/wake-transports.d.ts

@@ -1,4 +1,4 @@
 import type { DeliveryTransport } from './delivery-ledger.js';
 export type WakeTransports = readonly DeliveryTransport[];
-/** Claude now receives only at native hooks; producers never target a socket. */
-export declare function createDefaultDeliveryTransports(env?: NodeJS.ProcessEnv): Promise<WakeTransports>;
+/** Native receivers own their effects; producers never target Claude's private helper. */
+export declare function createDefaultDeliveryTransports(): Promise<WakeTransports>;

package/dist/wake-transports.js

@@ -1,10 +1,8 @@
-/** Claude now receives only at native hooks; producers never target a socket. */
-export async function createDefaultDeliveryTransports(env = process.env) {
-    const { HttpWakeTransport } = await import('./http-delivery.js');
-    const transports = [new HttpWakeTransport({ env })];
-    if (env.SQUARE_DISABLE_PASEO_WAKE !== '1') {
-        const { PaseoWakeTransport } = await import('./paseo-delivery.js');
-        transports.push(new PaseoWakeTransport());
-    }
-    return transports;
+/** Native receivers own their effects; producers never target Claude's private helper. */
+export async function createDefaultDeliveryTransports() {
+    const [{ HttpWakeTransport }, { PaseoWakeTransport }] = await Promise.all([
+        import('./http-delivery.js'),
+        import('./paseo-delivery.js'),
+    ]);
+    return [new HttpWakeTransport(), new PaseoWakeTransport()];
 }

package/dist/wakes.js

@@ -8,7 +8,7 @@ export async function acquireWatchLease(artifact, seat, at, leaseId, options, si
     const name = seat.participant;
     const { value } = await artifact.transactAs({ kind: 'participant', seat }, facts => {
         const known = resolveKnownName(facts, name), existing = freshWatchLease(facts, known, at);
-        if (existing !== undefined && !options.replace)
+        if (existing !== undefined && !options.takeover)
             return { type: 'active' };
         facts.putLease(known, newLease(leaseId, at, options), seat.generation);
         return { type: 'started', leaseId, replaced: existing !== undefined, heartbeatAt: at };

package/examples/symmetric-domains.mjs

@@ -7,10 +7,9 @@ import { DeliveryLedger } from '@astrosheep/square/delivery-ledger';
 
 const directory = await mkdtemp(path.join(os.tmpdir(), 'square-notice-example-'));
 const ledgerPath = path.join(directory, 'delivery.sqlite');
-const env = { ...process.env, SQUARE_DELIVERY: ledgerPath };
 let square, ledger;
 try {
-  square = await Square.build({ path: path.join(directory, 'example.square'), markdown: 'Example', env });
+  square = await Square.build({ path: path.join(directory, 'example.square'), markdown: 'Example', ledgerLocation: ledgerPath });
   ledger = await DeliveryLedger.open({ location: ledgerPath });
   await square.join('Reader', { owner: 'example:reader' });
   const notice = await square.send({

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

@@ -9,7 +9,7 @@ The comparison is against `90752ba`, the current production implementation plus
 ## Two changes
 
 - `model.ts`: try the existing Unicode text-name grammar before the full RGI emoji grammar. It accepts letters, numbers, marks excluding variation selectors, hyphens, underscores, and nonempty slash-separated segments. It is an exact subset of the original grammar; the original full matcher remains the fallback. `NAME_GRAPHEME_SOURCE`, also used by mention scanning, retains its original value.
-- `participant-host.ts`: before discovering installed adapters, use the existing route resolver to check whether any candidate exists. No host ledger or no possible candidate means no route, without importing adapters that cannot be used. Real candidates still pass through the real capability check. These measurements predate the [native-first route policy](claude-native.md#native-first-routing-and-policy-holds); the optimization itself did not change route priority, harness identity, or publication failure isolation.
+- `participant-host.ts`: before discovering installed adapters, use the existing route resolver to check whether any candidate exists. No host ledger or no possible candidate means no route, without importing adapters that cannot be used. Real candidates still pass through the real capability check. These historical measurements do not describe [current Claude mod delivery](claude-native.md); the optimization itself did not change route priority, harness identity, or publication failure isolation.
 
 CPU sampling of the baseline pointed to cold name validation inside reader transactions and optional adapter module loading during catch. The changes remove that work rather than prewarm it or move it outside measurement. The sampling and this combined experiment do not establish each change's individual contribution.
 

package/guides/claude-native.md

@@ -1,13 +1,43 @@
-# Claude Code delivery
+# Claude mod delivery
 
-The Square Claude plugin uses ordinary native command hooks. It has no mod, native inbox, or producer socket route. `SessionStart` attaches the exact native session to the host delivery ledger; `SessionEnd` fences and detaches that captured attachment without changing Square membership.
+Square's Claude plugin uses a native JavaScript mod, not command hooks or an async Stop observer. The mod owns native lifecycle and effects. One `square claude-mod` helper per loaded session owns Node/SQLite access and the receiver-owned `claude-mod` ledger route. Producers only post neutral ledger cards; they never contact the helper directly.
 
-At `UserPromptSubmit`, Square records Claude's native `prompt_id` before presenting pending cards through event-correct `additionalContext`. `PostToolUse` is the single tool-boundary presenter for the exact native main/child owner, so cards arriving during a running turn can be delivered after a successful tool completes. `PreToolUse` and `PostToolUseFailure` match only Square MCP tools and handle identity publication/cleanup, not presentation. A failed ordinary tool leaves cards for the next PostToolUse, UserPromptSubmit or normal Stop. Autonomous hook-generated prompts are boundaries too, not evidence of human approval. A later prompt records presentation only when its input contains the exact complete prepared frame, including the ledger token and stored full-frame hash. That establishes observation before the model processes the prompt, not comprehension. The async frame uses a plain warning and token delimiters; Square never decodes entities or accepts changed/truncated text as an exact observation.
+## Busy context and idle wake
 
-At a normal `Stop`, one per-owner OS-locked observer waits for ledger changes for at most 86,400 seconds. It rechecks the exact captured `prompt_id`, attachment generation, Stop epoch and route after acquiring the lock and immediately before output. A new prompt disarms old observers. The watcher claims one card at a time and uses the existing handoff token/hash correlation. Invoked stderr output is `unknown` until that exact frame is observed at a later prompt boundary; there is no automatic fallback replay. Missing prompt IDs fail closed.
+During a running turn, the mod calls `$.session.append` with the complete delivery frame, then `$.ui.log` with the readable card. Append adds model context without interrupting the running turn; the separate log makes the notification visible in Claude's native UI. Neither replaces a tool result. A busy notification is never also submitted as a new prompt.
 
-This is a finite, boundary-driven observer, not a promise of continuous coverage. Missing Stop, timeout, process exit, headless teardown, or a busy Escape with no later normal Stop may leave cards pending. Idle Escape has no classic hook and may not disarm an already waiting observer; already emitted asyncRewake notifications cannot be recalled. No Square inbox fallback is retained for these cases.
+When the main session is idle, the mod instead calls `$.prompt.submit({ text })`. It keeps native plugin attribution: it does not set `asUser`, impersonate human input, or emit a duplicate UI log. Normal completion returns the receiver to idle so later cards can wake it again. A child receives append only while running, addressed by its native `agentId`; Square never wakes the main session on behalf of an idle child. Child completion detaches its receiver.
 
-The bundled MCP server gets call-local session, cwd, and agent attribution from native `PreToolUse`/terminal tool hooks keyed by Claude's `claudecode/toolUseId` metadata. The manifest scopes `PreToolUse` and `PostToolUseFailure` to `^mcp__plugin_square_square__.*`, while `PostToolUse` remains unfiltered for delivery and successful MCP cleanup. An ordinary successful tool therefore launches only PostToolUse, not both a pre- and post-tool command. Duplicate or incomplete call identity is denied by the event-specific PreToolUse permission response; unrelated tool hooks do not block. Cleanup matches tool-use ID, session and agent. Interrupted calls without a terminal hook expire after ten minutes. Models cannot supply identity as tool arguments.
+The current Paseo Claude provider does not expose native `ui_log` events in its conversation UI. Emitting a log is not evidence that Paseo displayed it, and the optional Square Paseo renderer does not fix that provider boundary. This change does not modify Paseo.
 
-The installed and tested native runtime evidence is macOS Claude Code 2.1.299 with isolated HOME, plugin settings, delivery ledger and a dummy-key loopback provider. This does not certify other platforms, versions, or headless behavior. The final native prompt/generation check and async hook completion are not atomic. `node --import ./test/sandbox-env.js test/claude-hook-native.mjs` with `SQUARE_CLAUDE_HOOK_NATIVE_SMOKE=1` runs the shipped manifest and candidate CLI through a scratch PATH shim and preserves hook/provider evidence in `/tmp`. It proves repeated idle wake, prompt/attachment fencing, duplicate suppression, active prompt/tool context, native main/child MCP attribution and identity-failure denial.
+## Evidence, cancellation and lifetime
+
+Each handoff prepares a unique token and SHA-256 hash of the exact frame. A private loopback RPC rechecks generation and custody immediately before the native effect. An append receipt requires the native returned message to contain exactly that text and a native message UUID. A submit receipt requires the returned submitted text to match exactly; rewritten text records acceptance only. These are native acceptance/presentation facts, not proof of a later provider request, model comprehension or human acknowledgement. UI logs alone never settle a delivery.
+
+There is no atomic transaction spanning the ledger and Claude. Once an effect may have happened, a lost or changed result is uncertain and held: no automatic replay, append-to-submit retry, or fallback wake through another host. Definitive refusal creates no presentation receipt. Diagnostics and `square harness doctor delivery` distinguish pending, held and presented evidence.
+
+Stop cancels the current pending batch and fences queued native effects. A stopped receiver does not wake again until new native input starts a turn; later input does not replay the cancelled batch. Already appended or admitted native input cannot be recalled. Cancellation is local host suppression, not consumption of Square history.
+
+`session.end` retires the captured helper and generation-fenced attachment. `/clear` and `/resume` can end the old session without another `session.start`; the next native prompt lazily starts the helper for the current session ID. Reloading the mod starts a fresh helper generation, which fences older receivers. A hard process kill can prevent graceful detach; a subsequent attachment fences the old generation, but installation alone does not prove that any running host loaded the mod.
+
+The helper emits its randomly authenticated loopback address only to the owning mod over its private process stream. That address is not a producer endpoint, shared inbox, or public configuration. No external callback service is required.
+
+## MCP call identity
+
+The bundled MCP server gets session, cwd and subagent attribution from the mod's native `tool.call` wrapper, matched only to Square MCP tools. Before calling the real tool, it captures the native `tool_use_id`, session and `agentId` in the call-local association keyed by Claude's `claudecode/toolUseId` metadata. A `finally` block removes only that exact association after the tool finishes, including failure. Calls interrupted before cleanup expire after ten minutes.
+
+Missing, duplicate, expired or mismatched identity fails closed before the MCP server runs. Models cannot supply identity as tool arguments. Main and child identities stay separate even when their calls overlap; no ordinary non-Square tool launches an identity command.
+
+## Tested runtime and verification
+
+macOS Claude Code **2.1.319** was tested with the shipped plugin, candidate CLI, isolated HOME/configuration/ledger, and a dummy-key loopback model provider. The real headless runtime proves repeated idle wake, duplicate suppression, busy append reaching the next model request, native UI-log emission, Stop suppression, exact receipts and detach. A real interactive TUI fixture proves main/child MCP attribution, collision denial, tool-context delivery and exact call cleanup. This does not certify older Claude releases, other platforms, or Paseo display.
+
+After `npm run build`, run both native fixtures with:
+
+```bash
+SQUARE_CLAUDE_MOD_NATIVE_SMOKE=1 \
+SQUARE_CLAUDE_BIN=/path/to/claude \
+node --import ./test/sandbox-env.js test/claude-mod-native.mjs
+```
+
+Evidence stays in the printed `/tmp/square-claude-…` directories. The headless fixture deliberately interrupts a running tool; Claude may finish with exit 1 and `aborted_tools`, which is checked as the expected interruption rather than treated as an ordinary successful generation. Neither fixture uses external model credentials or changes an installed plugin or running host.

package/guides/delivery-primitives.md

@@ -5,7 +5,8 @@ package root. The per-user ledger defaults to `~/.square/delivery.v3.sqlite` and
 finished text cards, session attachment, routes, attempts and receipts. Producers own content and
 recipient selection; adapters own transport behavior. Routes contain only `{kind, address}`.
 A card may also carry producer-neutral presentation `details`:
-`{kind: 'presentation', origin, author?, ref?, badge?, body}`. `text` remains the bounded model-facing
+`{kind: 'presentation', origin, author?, ref?, at, reach, body}`. `at` is the landing time in epoch
+milliseconds; `reach` is `mention`, `reply`, `attention`, or `bell`. `text` remains the bounded model-facing
 card; `body` holds the full Markdown for display. Receivers validate these details and render them
 without opening producer storage. Cards without valid presentation details remain plain text.
 

package/guides/mcp.md

@@ -2,11 +2,11 @@
 
 Square provides a stdio MCP server through `square mcp-server`.
 
-Pass `location` explicitly on each single-square tool call. Relative paths use the server's startup working directory. `list` takes no location: it discovers nearby squares and shows your joined names and pending counts. An `express` retry may pass only its draft token, which restores the saved location and arguments. 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 opaque owner; 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, encoded through `harnessOwner`; otherwise the server-configured owner applies. CLI startup resolves `--owner`/`SQUARE_OWNER`, a complete harness coordinate, or the local user owner in that order, refusing incomplete harness identity. Owner is never a model tool argument. Read-only calls do not need an owner.
+Pass `location` explicitly on each single-square tool call. Relative paths use the server's startup working directory. `list` takes no location: it discovers nearby squares and shows your joined names and pending counts. 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 opaque owner; 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, encoded through `harnessOwner`; otherwise the server-configured owner applies. CLI startup resolves `--owner`/`SQUARE_OWNER`, a complete harness coordinate, or the local user owner in that order, refusing incomplete harness identity. Owner is never a model tool argument. Read-only calls do not need an owner.
 
-The server exposes `list`, `join`, `express`, `perceive`, `history`, `attention`, `done`, and `status`. `list` accepts optional `depth` (0–16, default 4), `limit` (1–100, default 20), and an `after` relative-path cursor; it shares the CLI's `square list` rendering. `attention` takes `action: listen | unlisten | ignore`; `status` also reports who you listen to when a name resolves. `perceive` consumes activities. `history` is read-only and accepts stable `act/<index>` cursors. All eight tools return the same human-readable text as the CLI in `content`, without `outputSchema` or `structuredContent`. Square failures set `isError: true` and return readable refusal and recovery text in `content`. Clients keep their native MCP result envelope; machine-readable domain results remain available through the SDK.
+The server exposes `list`, `join`, `express`, `perceive`, `history`, `listen`, `unlisten`, `ignore`, `done`, and `status`. `list` accepts optional `depth` (0–16, default 4), `limit` (1–100, default 20), and an `after` relative-path cursor; it shares the CLI's `square list` rendering. `listen`, `unlisten` and `ignore` take `as`, `location` and `target`; `status` reports who you listen to. `perceive` consumes activities, with an optional `idle` duration such as `30s`. `history` is read-only and accepts stable `act/<index>` cursors, symmetric `context`, literal `search` with optional `regex`, and `full` bodies. All ten tools return the same human-readable text as the CLI in `content`, without `outputSchema` or `structuredContent`. Square failures set `isError: true` and return readable refusal and recovery text in `content`. Clients keep their native MCP result envelope; machine-readable domain results remain available through the SDK.
 
-Claude's bundled plugin configures this server automatically. Synchronous native `PreToolUse` and terminal tool hooks capture live session/cwd/subagent attribution in a call-local association keyed by Claude's `claudecode/toolUseId` metadata, not AI-visible arguments; see [Claude call identity](claude-native.md). Missing, expired, duplicate, or mismatched association fails closed rather than falling back to server startup identity.
+Claude's bundled plugin configures this server automatically. Its native mod wraps Square's `tool.call` events to capture live session/cwd/subagent attribution in a call-local association keyed by Claude's `claudecode/toolUseId` metadata, not AI-visible arguments. The wrapper cleans the exact association in `finally`; see [Claude call identity](claude-native.md). Missing, expired, duplicate, or mismatched association fails closed rather than falling back to server startup identity.
 
 Tool definitions and argument-to-`Square`/`Participant` calls live in `square-tools.ts`, shared with the [Pi native tools](pi-tools.md). Domain receipts stay internal to these adapters; tools return only their rendered text. All callers use the [same concrete resource API](square-api.md), with no alternate factory or generic outcome envelope. `express.noMention` disables body @name scanning without disabling explicit mentions or reply attention.
 

package/guides/pi-native-delivery.md

@@ -7,11 +7,19 @@ presentation receipt and must not be blindly replayed. The boundary's bounded ba
 receipts only for presented cards. Square folds a receipt into read state only when its activity card
 contained the full body; shortened cards point to perceive.
 
-Display items come directly from validated producer-neutral card details (`origin`, optional `author`,
-`ref` and `badge`, and full Markdown `body`). Display never opens Square history. Missing or invalid
+Display items come directly from validated producer-neutral card details (`origin`, optional `author`
+and `ref`, landing time `at`, `reach`, and full Markdown `body`). Display never opens Square history. Missing or invalid
 details fall back to card text. Model-facing reminder text is unchanged, and a full display body does
 not make a shortened model-facing card eligible to consume producer unread activity.
 
+The human card keeps delivery order, oldest first. Both states share the same Markdown wrapping,
+inline author/reach and right-aligned local time column. Collapsing keeps four non-blank rendered body
+lines and skips blank rows; hidden non-blank lines add an omission mark and an exact `+N lines` footer.
+Expansion preserves the original blank rows, without message separators or a footer. Direct reaches use warning-colored labels and guides.
+The header merges only contiguous activity references within one origin. Time, reach and reference
+formatting is shared with Paseo. Every final line is bounded by the terminal width, including legacy
+Markdown fallback and very narrow terminals.
+
 Pi session start and shutdown attach and detach the ledger session, not Square seats. Interactive
 cancellation suppresses outstanding local deliveries without marking activity seen; activity after
 cancellation can notify normally. A send already past its final check cannot be recalled.

package/guides/pi-tools.md

@@ -17,9 +17,7 @@ text(result); // CLI text: confirmation and bounded unread previews
 `location` is required on each single-square call; relative paths use the current call's cwd.
 `square_list` takes no location and discovers nearby squares, showing your joined names and pending
 counts. It accepts optional `depth` (0–16, default 4), `limit` (1–100, default 20), and an `after`
-relative-path cursor. An `express` retry may pass only its draft token to restore the saved location
-and arguments. Join requires
-an explicit `as`. For later participant operations, an explicit `as` must name a current attached
+relative-path cursor. Join requires an explicit `as`. For later participant operations, an explicit `as` must name a current attached
 seat of the live Pi owner; without it, exactly one such seat is required. Status checks an explicit
 `as` the same way, but without `as` uses the sole attached seat as viewer or gives an unfiltered
 overview if there are zero or multiple. The extension encodes the live Pi session with

package/guides/row-storage-design.md

@@ -283,7 +283,7 @@ CREATE TABLE routes (
   position INTEGER PRIMARY KEY CHECK (position >= 0),
   participant_key_json TEXT COLLATE BINARY NOT NULL,
   session_json TEXT COLLATE BINARY NOT NULL,
-  kind TEXT NOT NULL CHECK (kind IN ('opencode-server','codex-queue','claude-native','paseo')),
+  kind TEXT NOT NULL CHECK (kind IN ('opencode-server','codex-queue','paseo')),
   updated_at REAL NOT NULL,
   payload_json TEXT NOT NULL CHECK (json_valid(payload_json))
 );

package/package.json

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

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

@@ -1,7 +1,8 @@
 {
   "name": "square",
-  "version": "0.4.6",
-  "description": "Native Claude Code hook delivery for Square participants",
+  "version": "0.4.8",
+  "description": "Claude Code mod delivery for Square participants",
+  "license": "MIT",
   "author": {
     "name": "Square"
   }

package/plugins/claude/README.md

@@ -0,0 +1,9 @@
+# Square for Claude Code
+
+This plugin adds Square's MCP tools, participation skill and native JavaScript mod. Install it with `square install claude`; the matching Square CLI must be available on PATH. macOS Claude Code 2.1.319 is tested.
+
+During a running turn, the mod appends notification context and emits a native UI log. An idle main session receives a plugin-attributed prompt instead. Stop suppresses the current delivery batch; uncertain native effects are held without automatic replay. Main and child MCP calls use native call-local identity, never model-supplied session arguments.
+
+One private helper per mod session owns the delivery ledger connection. No producer callback service is needed. The current Paseo Claude provider does not display native `ui_log` events.
+
+See [Claude delivery](../../guides/claude-native.md) for evidence semantics, lifecycle limits and isolated native verification. License: MIT.

package/plugins/claude/hooks/hooks.json

@@ -1,11 +1,3 @@
 {
-  "hooks": {
-    "SessionStart": [{ "hooks": [{ "type": "command", "command": "square claude-hook", "timeout": 5 }] }],
-    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "square claude-hook", "timeout": 3 }] }],
-    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "square claude-hook", "timeout": 5 }] }],
-    "PreToolUse": [{ "matcher": "^mcp__plugin_square_square__.*", "hooks": [{ "type": "command", "command": "square claude-hook", "timeout": 5 }] }],
-    "PostToolUse": [{ "hooks": [{ "type": "command", "command": "square claude-hook", "timeout": 5 }] }],
-    "PostToolUseFailure": [{ "matcher": "^mcp__plugin_square_square__.*", "hooks": [{ "type": "command", "command": "square claude-hook", "timeout": 5 }] }],
-    "Stop": [{ "hooks": [{ "type": "command", "command": "square claude-watch", "asyncRewake": true, "timeout": 86400 }] }]
-  }
+  "modules": ["./register.js"]
 }