@astrosheep/square 0.3.77 → 0.3.79

package/dist/square-tools.js

@@ -1,41 +1,47 @@
 import { z } from 'zod/v4';
 import { isSquareError } from './model.js';
 const location = z.string().optional().describe('Path to the .square artifact, relative to the current working directory. Defaults to the configured square.');
-const participant = z.string().optional().describe('Participant name, same as --as. Defaults to the configured participant or the current session’s unambiguous participant.');
+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());
 function tool(name, description, shape, run) {
     const inputSchema = z.object({ ...shape, location }).strict();
-    return { name, description, inputSchema, run: (app, args, control) => {
+    return { name, description, inputSchema, run: (square, args, control) => {
             const { location: _location, ...operationArgs } = inputSchema.parse(args);
-            return run(app, operationArgs, control);
+            return run(square, operationArgs, control);
         } };
 }
 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', 'Join the square as a participant.', { as: participant, takeover: z.boolean().optional().describe('Take the name from its current session owner.') }, (app, { takeover }, control) => app.join({ takeover }, control)),
-    tool('express', 'Express a message or embodied action in the square. Mentions and replies direct attention; bell reaches everyone. Bare activity is valid even with no listeners.', {
+    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 }, control);
+        return { ...receipt, participant: participant.name };
+    }),
+    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.'),
-    }, (app, { body, as: _participant, ...options }, control) => app.express(body, options, control)),
+    }, async (square, { body, as, ...options }, control) => {
+        const { delivery: _delivery, ...result } = await (await square.participant(as)).express(body, options, control);
+        return result;
+    }),
     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(),
-    }, (app, { as: _participant, ...options }, control) => app.catch(options, control)),
+    }, async (square, { as, ...options }, control) => (await square.participant(as)).catch(options, control)),
     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(),
-    }, (app, args, control) => app.history(args, control)),
-    tool('listen', 'Listen for future bare activity from a participant, clearing any ignore of them.', { as: participant, target: z.string() }, (app, { target }, control) => app.listen(target, control)),
-    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() }, (app, { target }, control) => app.ignore(target, control)),
-    tool('listening', 'List participants this participant is listening to.', { as: participant }, (app, _args, control) => app.listening(control)),
-    tool('hold', 'Raise a hand to hold the square.', { as: participant, reason: z.string().optional() }, (app, { reason }, control) => app.hold(reason, control)),
-    tool('resume', 'Release the current hold.', { as: participant }, (app, _args, control) => app.resume(control)),
-    tool('done', 'Leave the square without adding a message.', { as: participant }, (app, _args, control) => app.done(undefined, control)),
-    tool('status', 'Read the public status of the square.', {}, (app, _args, control) => app.status(undefined, control)),
-    tool('participants', 'List participants standing in or done with the square.', {}, (app, _args, control) => app.participants(control)),
+    }, (square, args, control) => square.history(args, control)),
+    tool('listen', 'Listen for future bare 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, {}, control)),
+    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, {}, control)),
+    tool('listening', 'List participants this participant is listening to.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).listening({}, control)),
+    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, {}, control)),
+    tool('resume', 'Release the current hold.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).resume({}, control)),
+    tool('done', 'Leave the square without adding a message.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).done(undefined, {}, control)),
+    tool('status', 'Read the public status of the square.', {}, (square, _args, control) => square.status({}, control)),
+    tool('participants', 'List participants standing in or done with the square.', {}, (square, _args, control) => square.participants({}, control)),
 ];
 export function squareToolFailure(error, signal) {
     const normalized = signal?.aborted

package/dist/stream.d.ts

@@ -1,3 +1,3 @@
-import type { OpenOptions, OperationControl, StreamApplicationOptions, StreamApplicationRecord } from './square-facade.js';
+import type { OpenOptions, OperationControl, StreamOptions, StreamRecord } from './square-facade.js';
 /** Pull-based observation; return interrupts an outstanding pull before awaiting its cleanup. */
-export declare function streamSquare(squarePath: string, options?: StreamApplicationOptions, control?: OperationControl, openOptions?: OpenOptions): AsyncIterable<StreamApplicationRecord>;
+export declare function streamSquare(squarePath: string, options?: StreamOptions, control?: OperationControl, openOptions?: OpenOptions): AsyncIterable<StreamRecord>;

package/dist/views.d.ts

@@ -2,8 +2,8 @@ import { type ActivityId } from './square-core.js';
 import { type StoredAct } from './model.js';
 import type { OpenSquare } from './open-square.js';
 import type { ActivityFilter, SquareRead } from './ports.js';
-import type { Activity, ApplicationOutcome, ArchiveRecord, HistoryQuery, HistoryApplicationQuery, HistoryContinuation, OperationControl, ParticipantStatus, ParticipantsApplicationData, ParticipantsProjection, SquareSnapshot, RecoveryObservation, EntryPresentation, ListPresentation, StatusApplicationData, StatusProjection, SquareContextProjection, CatchPresence, StreamProjection, EventPresentation } from './square-facade.js';
-export type { RecoveryObservation, EntryPresentation, ListPresentation, CatchPresence, StreamProjection } from './square-facade.js';
+import type { Activity, ArchiveRecord, HistoryQuery, HistoryContinuation, OperationControl, ParticipantsResult, SquareSnapshot, EntryPresentation, ListPresentation, StatusResult, SquareObservation, CatchPresence, StreamProjection } from './square-facade.js';
+export type { EntryPresentation, ListPresentation, CatchPresence, StreamProjection } from './square-facade.js';
 export declare const HISTORY_DEFAULT_LIMIT = 10;
 export declare const HISTORY_MAX_LIMIT = 100;
 export declare const NON_READ: readonly ["join", "done", "say", "hold", "resume", "listen", "ignore"];
@@ -11,29 +11,33 @@ export declare const NON_READ: readonly ["join", "done", "say", "hold", "resume"
 export declare function toPublicActivity(stored: StoredAct): Activity;
 export declare function parseRequiredActivityId(id: ActivityId): number;
 /** Compile the public query directly to typed selectors; only search hydrates unselected bodies. */
-export declare function selectHistory(facts: SquareRead, query: HistoryApplicationQuery, limit: number | null, kinds: ActivityFilter['kinds'], presentation?: boolean): {
+export declare function selectHistory(facts: SquareRead, query: HistoryQuery, limit: number | null, kinds: ActivityFilter['kinds'], presentation?: boolean): {
     continuation?: HistoryContinuation | undefined;
     activities: StoredAct[];
     visibleActivities: StoredAct[];
     totalMatches: number;
 };
 export declare function publicActivities(activities: readonly ArchiveRecord[]): Activity[];
-export declare function history(square: OpenSquare, query?: HistoryQuery, control?: OperationControl): Promise<Activity[]>;
 export declare function resolveParticipant(square: OpenSquare, name: string, control?: OperationControl): Promise<{
     name: string;
 }>;
 export declare function currentParticipant(square: OpenSquare, name: string, control?: OperationControl): Promise<string | undefined>;
-export declare function participants(square: OpenSquare): Promise<ParticipantStatus[]>;
 export declare function snapshot(square: OpenSquare, control?: OperationControl): Promise<SquareSnapshot>;
-export declare function recoveryObservation(square: OpenSquare, name: string, control?: OperationControl): Promise<RecoveryObservation>;
+export declare function recoveryObservation(square: OpenSquare, name: string, control?: OperationControl): Promise<{
+    ownActivityCount: number;
+    hardCap: import("./model.js").HardCap;
+    holdReason?: string | undefined;
+    participant: string;
+    roster: string[];
+    activitySummaries: import("./square-facade.js").UnreadActivitySummary[];
+    standingCount: number;
+    held: boolean;
+}>;
 export declare function entryPresentation(square: OpenSquare, name: string, lastN?: number | null, control?: OperationControl): Promise<EntryPresentation>;
-type ParticipantQueryContext = Pick<SquareContextProjection, 'location' | 'now' | 'automaticDeliveryAvailable'>;
-export declare function queryParticipants(facts: SquareRead, context: ParticipantQueryContext): ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection>;
-export declare function queryParticipants(facts: SquareRead, context: ParticipantQueryContext, presentation: boolean): ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection, boolean>;
+type ParticipantQueryContext = Pick<SquareObservation, 'location' | 'now' | 'automaticDeliveryAvailable'>;
+export declare function queryParticipants(facts: SquareRead, context: ParticipantQueryContext, observe?: boolean): ParticipantsResult;
 export declare function listPresentation(square: OpenSquare, control?: OperationControl): Promise<ListPresentation>;
-export declare function queryStatus(facts: SquareRead, context: ParticipantQueryContext, viewer?: string): ApplicationOutcome<StatusApplicationData, StatusProjection>;
-export declare function queryStatus(facts: SquareRead, context: ParticipantQueryContext, viewer: string, presentation: boolean): ApplicationOutcome<StatusApplicationData, StatusProjection, boolean>;
-export declare function eventPresentation(square: OpenSquare, id: ActivityId, control?: OperationControl): Promise<EventPresentation>;
+export declare function queryStatus(facts: SquareRead, context: ParticipantQueryContext, viewer?: string, observe?: boolean): StatusResult;
 export declare function catchPresence(square: OpenSquare, control?: OperationControl): Promise<CatchPresence>;
 export declare function streamProjection(square: OpenSquare, cursor: number, recipient?: string, control?: OperationControl): Promise<StreamProjection>;
 export declare function streamTailProjection(square: OpenSquare, last?: number, recipient?: string, control?: OperationControl): Promise<StreamProjection>;

package/dist/views.js

@@ -104,9 +104,6 @@ export function selectHistory(facts, query, limit, kinds, presentation = true) {
 export function publicActivities(activities) {
     return activities.flatMap((activity) => activity.kind === 'read' || activity.actor === undefined ? [] : [toPublicActivity(activity)]);
 }
-export async function history(square, query = {}, control) {
-    return (await square.artifact.read((facts) => publicActivities(selectHistory(facts, query, query.limit ?? null, NON_READ).activities), control?.signal)).value;
-}
 export async function resolveParticipant(square, name, control) {
     return (await square.artifact.read((facts) => ({ name: resolveKnownName(facts, name) }), control?.signal)).value;
 }
@@ -119,9 +116,6 @@ function statuses(facts, now) {
         return { name: p.name, state: p.state === 'done' ? 'done' : 'joined', consumedThrough: cursor < 0 ? null : formatActivityId(cursor), watching: p.presence === 'watching', listening: p.listening };
     });
 }
-export async function participants(square) {
-    return (await square.artifact.read((facts) => statuses(facts, square.clock()))).value;
-}
 export async function snapshot(square, control) {
     return (await square.artifact.read((facts) => {
         const header = facts.header(), hold = facts.hold();
@@ -136,19 +130,19 @@ export async function snapshot(square, control) {
 export async function recoveryObservation(square, name, control) {
     return (await square.artifact.read((facts) => {
         const known = resolveKnownName(facts, name), hold = facts.hold();
-        return { name: known, roster: rosterNames(facts), activitySummaries: unreadActivitySummaries(facts, known, square.clock()), participantCount: inSquareCount(facts), held: hold.active,
+        return { participant: known, roster: rosterNames(facts), activitySummaries: unreadActivitySummaries(facts, known, square.clock()), standingCount: inSquareCount(facts), held: hold.active,
             ...(hold.reason === undefined ? {} : { holdReason: hold.reason }), ownActivityCount: facts.participant(known).sayCount, hardCap: facts.header().hardCap };
     }, control?.signal)).value;
 }
 export async function entryPresentation(square, name, lastN = HISTORY_DEFAULT_LIMIT, control) {
     return (await square.artifact.read((facts) => {
-        const header = facts.header(), p = facts.participant(name);
+        const header = facts.header();
         const recentActivities = selectHistory(facts, {}, lastN, ['say', 'done']).activities;
-        return { joined: p?.joined ?? false, joinedBefore: facts.activityCount({ kinds: ['join'], actors: [name] }) > 1,
-            scene: header.warmup.join('\n').trim(), context: header.preamble.join('\n').trim(),
+        return { joinedBefore: facts.activityCount({ kinds: ['join'], actors: [name] }) > 1,
+            scene: header.warmup.join('\n').trim(),
             joinContext: (header.preamble.at(-1) === '---' ? header.preamble.slice(0, -1) : header.preamble).join('\n').trim(), recentActivities,
             perceptions: Object.fromEntries(recentActivities.map((a) => [a.index, perceiveActivity(facts, a, name)])),
-            sayNumbers: facts.sayOrdinals(recentActivities.map((a) => a.index)), participantCount: inSquareCount(facts), held: facts.hold().active };
+            sayNumbers: facts.sayOrdinals(recentActivities.map((a) => a.index)) };
     }, control?.signal)).value;
 }
 function classifyPresence(participants, now) {
@@ -160,10 +154,10 @@ function classifyPresence(participants, now) {
         classificationByName: Object.fromEntries(participants.map((participant) => [participant.name, participant.state === 'done' ? 'done'
                 : participant.state === 'not joined' ? 'not-joined' : hereNames.has(participant.name) ? 'here' : 'lingering'])) };
 }
-export function queryParticipants(facts, context, presentation = true) {
+export function queryParticipants(facts, context, observe = false) {
     const participants = coreParticipants(facts, context.now);
-    return { data: { participants }, projection: !presentation ? undefined : { ...context, ...classifyPresence(participants, context.now),
-            standingCount: inSquareCount(facts), held: facts.hold().active } };
+    return { participants, ...(!observe ? {} : { observation: { ...context, ...classifyPresence(participants, context.now),
+                standingCount: inSquareCount(facts), held: facts.hold().active } }) };
 }
 export async function listPresentation(square, control) {
     return (await square.artifact.read((facts) => {
@@ -174,7 +168,7 @@ export async function listPresentation(square, control) {
         return { context: facts.header().preamble, participants, activities: facts.activityCount({ kinds: ['say'] }) };
     }, control?.signal)).value;
 }
-export function queryStatus(facts, context, viewer = '', presentation = true) {
+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 latest = facts.activityHeads({ kinds: ['say', 'done'] }, { edge: 'newest', limit: 1 }).items[0];
@@ -191,15 +185,15 @@ export function queryStatus(facts, context, viewer = '', presentation = true) {
         participants: participants.filter((p) => p.state !== 'not joined'), now: context.now,
         ...(latestAct === undefined || latestAct.actor === undefined || latestAct.kind === 'read' ? {} : { latestActivity: toPublicActivity(latestAct) }),
     };
-    if (!presentation)
-        return { data, projection: undefined };
+    if (!observe)
+        return data;
     const afterIndex = latestAct?.index ?? -1;
     const joins = facts.activities(facts.activityHeads({ kinds: ['join'], afterIndex }, { edge: 'newest', limit: 3 }).items.map((h) => h.index)).map((activity) => ({ activity,
         rejoined: facts.activityCount({ kinds: ['done'], actors: [activity.actor], actorMatch: 'exact', beforeIndex: activity.index }) > 0 }));
     const canonicalViewer = facts.participant(viewer)?.name ?? viewer;
     return {
-        data,
-        projection: {
+        ...data,
+        observation: {
             ...context, ...classifyPresence(participants, context.now), standingCount, held: hold.active,
             knownParticipantCount: participants.length, viewer: canonicalViewer,
             ...(canonicalViewer === '' ? {} : { participant: canonicalViewer }),
@@ -210,14 +204,6 @@ export function queryStatus(facts, context, viewer = '', presentation = true) {
         },
     };
 }
-export async function eventPresentation(square, id, control) {
-    return (await square.artifact.read((facts) => {
-        const activity = facts.activity(parseRequiredActivityId(id));
-        if (activity === undefined)
-            throw new SquareError('invalid_args', `Unknown activity id: ${id}`);
-        return { activity, participantCount: inSquareCount(facts), held: facts.hold().active };
-    }, control?.signal)).value;
-}
 export async function catchPresence(square, control) {
     return (await square.artifact.read((facts) => {
         const now = square.clock();

package/guides/application-demand-optimization.md

@@ -1,5 +1,10 @@
 # Application presentation demand
 
+> **Historical evidence, superseded API.** The factory/outcome shapes and split SDK defaults
+> below describe the earlier implementation, not current instructions. Use the real
+> [Square/Participant API](square-api.md); the independent factory and its design guide are deleted.
+
+
 ## Design
 
 `createSquareApplication(context)` retains complete terminal-facing outcomes. MCP uses `createSquareApplication(context, { presentation: false })`; its outcome has the same `data` contract and `projection: undefined`.

package/guides/application-facade-delivery-evidence.md

@@ -1,6 +1,11 @@
 # Shared application boundary: delivery evidence
 
-Deliverer evidence, **not independent review or acceptance**. Design and the complete caller/deletion map are in [application-facade-design](application-facade-design.md).
+> **Historical evidence, superseded API.** The factory/outcome shapes and split SDK defaults
+> below describe the earlier implementation, not current instructions. Use the real
+> [Square/Participant API](square-api.md); the independent factory and its design guide are deleted.
+
+
+Deliverer evidence, **not independent review or acceptance**. The historical caller/deletion map is recorded below; current ownership is described in [Square/Participant API](square-api.md).
 
 ## Candidate coordinates
 

package/guides/claude-native.md

@@ -75,7 +75,9 @@ old ends cannot retire that replacement. Unchanged reload preserves epochs.
 ## Body, admission, and presentation
 
 The coordinator uses Square's canonical audience projection and bounded body
-preview. A clipped preview ends with the full `catch --id act/<index>` command.
+preview. Each notification identifies the square, receiving participant and
+activity before its event and body. A clipped preview describes catching that
+activity to read it in full; it never embeds shell commands or tool-call syntax.
 Opaque text correlation resolves through bound memberships and the existing
 attempt ledger, never a path or asserted source from incoming text.
 

package/guides/mcp-connection-lifetime.md

@@ -1,8 +1,8 @@
 # MCP connection lifetime
 
-An MCP server owns one artifact connection for its configured square. Its lifetime ends on close or disconnect; create a new server instance for a new connection. Replacing an artifact file under a running server remains unsupported. Every tool call still creates an application with that request's participant and harness session. Calls with an explicit `location` override instead open and close a per-call connection, leaving the configured-square owner untouched. Only the default connection is shared: authorization, presence, activity facts and cancellation remain operation-scoped. The artifact port already serializes transactions on its connection.
+An MCP server owns one artifact connection for its configured square. Its lifetime ends on close or disconnect; create a new server instance for a new connection. Replacing an artifact file under a running server remains unsupported. Every tool call opens an actual `Square` handle with that request's captured environment, default participant and harness session; `square.participant()` performs nonmutating name selection. Calls with an explicit `location` override instead open and close a per-call connection, leaving the configured-square owner untouched. Only the default connection is shared: authorization, presence, activity facts and cancellation remain operation-scoped. The artifact port already serializes transactions on its connection.
 
-`createSquareResourceOwner()` is the explicit lifetime boundary. `scoped()` borrows its connection; ordinary application callers still open and close their own. Cross-square `inbox()` reads remain independent. The connection captures no request abort signal. Explicit server close and transport disconnect share one shutdown path: the SDK cancels requests, handlers finish their cleanup, then the connection closes.
+`createSquareResourceOwner()` is the explicit lifetime boundary. `Square.at({resources, ...})` borrows its connection; closing a request handle leaves the owner open. Ordinary callers open and close their own Square. Cross-square `inbox()` reads remain independent. The connection captures no request abort signal. Explicit server close and transport disconnect share one shutdown path: the SDK cancels requests, handlers finish their cleanup, then the connection closes.
 
 ## Local measurement
 

package/guides/mcp.md

@@ -8,6 +8,6 @@ The server exposes `join`, `express`, `catch`, `history`, `listen`, `ignore`, `l
 
 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.
 
-Tool definitions and argument-to-facade calls live in `square-tools.ts`, shared with the [Pi native tools](pi-tools.md). `express.noMention` disables body @name scanning without disabling explicit mentions or reply attention.
+Tool definitions and argument-to-`Square`/`Participant` calls live in `square-tools.ts`, shared with the [Pi native tools](pi-tools.md). Join serializes the handle's name and receipt fields, never resource internals. 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.
 
 Configure a client with command `npx` and arguments `--yes --package @astrosheep/square square mcp-server`, or use the installed `square` executable with argument `mcp-server`. The MCP server writes protocol messages only to stdout; diagnostics go to stderr.

package/guides/migration.md

@@ -6,7 +6,8 @@ sparse receipts, catch leases, ordered routes and the small configuration
 facts — in one in-place database.
 
 Existing artifacts are **not** converted automatically. A normal read of a
-version 1 artifact refuses with the exact command to run:
+version 1 artifact refuses with a descriptive offline-migration requirement.
+The CLI adds the concrete recovery command; native tools retain the description:
 
 ```sh
 square --location /path/to/SQUARE.square migrate

package/guides/operation-cancellation.md

@@ -14,4 +14,6 @@ The single-root HostLedgerPort passes `(input, signal)` for cancellable claims;
 
 Ownership and delivery have the same limitation: cancellation can stop work that has not entered the boundary, but it cannot withdraw an ownership effect or a transport send that already happened. The returned committed result and existing degradation classification remain authoritative.
 
+The same `Square`/`Participant` methods serve SDK and adapters; see [resource API](square-api.md). Join, listener and lifecycle essential observations use commit-time facts. Join's optional entry enrichment may be unavailable without rejecting its successful receipt. CLI express passes its abort signal through the initial `Square.at`; raw draft saving precedes a separate uncancelled recovery reopen.
+
 Pi notification cancellation is separate and unchanged.

package/guides/primitive-catch-consolidation.md

@@ -1,5 +1,10 @@
 # Canonical catch selection — delivery evidence
 
+> **Historical evidence, superseded API.** The factory/outcome shapes and split SDK defaults
+> below describe the earlier implementation, not current instructions. Use the real
+> [Square/Participant API](square-api.md); the independent factory and its design guide are deleted.
+
+
 Deliverer evidence only, **not independent review or acceptance**.
 
 ## Coordinates and lane attribution

package/guides/primitive-history-consolidation.md

@@ -1,5 +1,10 @@
 # History query consolidation — delivery evidence
 
+> **Historical evidence, superseded API.** The factory/outcome shapes and split SDK defaults
+> below describe the earlier implementation, not current instructions. Use the real
+> [Square/Participant API](square-api.md); the independent factory and its design guide are deleted.
+
+
 Deliverer evidence, not an independent review or acceptance.
 
 ## Coordinates and lane-local reduction

package/guides/primitive-status-consolidation.md

@@ -1,5 +1,10 @@
 # Canonical status and participant queries — delivery evidence
 
+> **Historical evidence, superseded API.** The factory/outcome shapes and split SDK defaults
+> below describe the earlier implementation, not current instructions. Use the real
+> [Square/Participant API](square-api.md); the independent factory and its design guide are deleted.
+
+
 Deliverer evidence, not independent review or acceptance.
 
 ## Coordinates and lane attribution

package/guides/primitive-storage-consolidation.md

@@ -1,5 +1,10 @@
 # Artifact and resource primitive consolidation
 
+> **Historical evidence, superseded API.** The factory/outcome shapes and split SDK defaults
+> below describe the earlier implementation, not current instructions. Use the real
+> [Square/Participant API](square-api.md); the independent factory and its design guide are deleted.
+
+
 Deliverer evidence, not independent review or acceptance.
 
 ## Coordinates and scope

package/guides/row-storage-design.md

@@ -414,7 +414,7 @@ No production structure below carries `.state`, all `.activities`, or a deferred
 |---|---|
 | openSquare/openSquareArtifact, wait baselines, watch headers, cli/program | header/revision only; remove preliminary whole-state validation/load. Every normal selected-row decode remains validated. |
 | square-actions join/implicitJoin/takeover/done/endOwnedSession, registry-associated route cleanup | participant/roster as needed, routes, land/replaceRoutes; same host claim lock scopes and cleanup sequences. Takeover done+join is one txn. No full SDK snapshot. |
-| createSquareApplication.join's before/after snapshot and CLI hold/resume/done count calls | new internal `joinFacts(name)` projection = requested participant, known joined-or-done count, standing count. Before conflict pending uses known joined-or-done count as today; application's participantCount keeps its existing known joined-or-done semantics. CLI header after hold/resume/done uses standing count. Wire private helpers on Square/context rather than calling public snapshot. |
+| Join's before/after snapshot and CLI hold/resume/done count calls | Current `Square.join` returns its concrete receipt with a Participant handle; optional observations use transaction-captured counts, held state and time. Listener/lifecycle commit facts likewise come from the mutation transaction; join's extra entry history is best-effort. Known joined-or-done `participantCount` remains distinct from the standing count. See [Square/Participant API](square-api.md). |
 | express/decideAct and behind rendering (activity.ts) | header, actor fact, roster for longest standing-body mention resolution, hold, reply head/existence, recentSayTimes, continuous cursor, directed suffix. Admission normalization/error order unchanged. A valid reply coordinate is <nextActIndex, even if a gap: preserve current acceptance of assigned-but-missing reply. ActivityPresentation supplies own count/cap/hold/roster, suffix items with lifetime ordinals + settled full perception, and behind summaries. No whole history used just to number previews. |
 | listen/ignore/listening, watch leases and terminal checks | actor fact, outgoing attention; roster only for quorum; land or lease methods. Unknown valid attention target still allowed. Pulse keeps hold-before-terminal priority. |
 | catch / native seen | directed selectors/activity exact, markSeen, cursor/counts in txn; native `current` becomes synchronous `(facts: SquareRead)=>boolean`, evaluated ONLY within reads/receipt txn. It cannot escape or call host I/O. |
@@ -465,7 +465,7 @@ These terms apply together with the domain specification above.
 ## Migration protocol
 
 - Only `square --location <path.square> migrate`. No --check, --backup, --force, auto-migrate, bulk mode, separate lock database, sidecar, daemon, or runtime dual reader. An operator can make an offline backup with ordinary tooling; the command does not invent a backup lifecycle.
-- application_id remains 0x53515245; user_version 2 identifies rows. Normal new-format reads/writes refuse version 1 with invalid_args / reason migration_required and a shell-quoted full migration command. build --force does not bypass it. Unknown/unrelated/invalid formats are refused, not repaired.
+- application_id remains 0x53515245; user_version 2 identifies rows. Normal new-format reads/writes refuse version 1 with invalid_args / reason migration_required and descriptive offline-migration guidance. The CLI adds the shell-quoted recovery command; native tool errors do not embed invocation syntax. build --force does not bypass it. Unknown/unrelated/invalid formats are refused, not repaired.
 - `doctor` remains read-only: recognizes legacy v1 and prints the migration recovery command (exit 2); validates v2 fully, including a replay comparison of derived indices. It must not imply that legacy v1 is damaged. Directory/list probing retains omission semantics for unsupported files; no new implicit migration/discovery subsystem.
 - Open existing canonical path create-disabled. A read-only preflight establishes owned known schema/version before any persistent pragma or DDL. Require existing DELETE journal mode, refuse another mode without changing it; the shipped v1 creator/writer already establishes DELETE. Set connection busy_timeout=0 and synchronous=FULL. Acquire BEGIN IMMEDIATE, re-check format/schema under the lock, and validate the full v1 snapshot inside it. If v2 is already present and has valid framing/header, return already-format-2 without changing revision. A second migrator follows this same in-lock check.
 - Use v1 validation retained ONLY in migration (test oracle may also retain it), plus one explicit restriction: non-finite numbers anywhere in a route (including nested extras) are unsupported input, refused before DDL/inserts with the artifact untouched. They are not normally persisted as non-finite values by the v1 JSON.stringify writer; do not add a bespoke overflow-number codec or silently coerce to null. Copy normally persisted authoritative facts losslessly, preserving revision and nextActIndex, activity indices/gaps and optional field distinctions, raw receipt/lease owner keys, route order/duplicates, strings and finite fractional timestamps. Absent routes and [] both become zero rows; empty receipt-owner maps are behaviorless and may become zero receipt rows. Do not canonicalize receipts or add foreign keys that reject accepted v1 facts.

package/guides/square-api.md

@@ -0,0 +1,107 @@
+# Square and Participant API
+
+`Square` is the actual resource handle shared by SDK, CLI, MCP and Pi. Its implementation is
+`square-api.ts`; `square.ts` remains the executable CLI entrypoint. `square-facade.ts` contains
+only public types. There is no separate operation factory, dispatcher or `{data, projection}` envelope.
+
+## Open, select, join, close
+
+```ts
+import { Square } from '@astrosheep/square';
+
+const square = await Square.at({ path: './PUBLIC.square', env: { ...process.env } });
+try {
+  const joined = await square.join('Alice');
+  const alice = joined.participant;
+  const sent = await alice.express('Hello @Bob', { force: true });
+  const page = await square.history();
+  console.log(sent.activity.id, page.activities);
+} finally {
+  await square.close();
+}
+```
+
+- `Square.build({path, markdown, hardCap?, throttlePerMinute?, template?, force?, ...})` returns
+  the same open resource. `Square.inMemory({markdown, ...})` is synchronous and creates no default
+  native wake transport.
+- `Square.at` accepts `path`, optional `cwd`, captured `env`, `clock`, `hostLedger`, `wakeTransport`
+  and default `participant`. An omitted path uses captured `SQUARE_LOCATION`; relative paths use
+  `cwd`. Explicit participant, configured default, nonblank captured `SQUARE_PARTICIPANT_NAME`,
+  then an unambiguous current-session ledger binding determine a name, in that order.
+- `await square.participant(name?)` selects a handle **without joining, claiming or reentering**.
+  Discovery happens on each selection, not through a cached session-to-name decision.
+- `square.join(name?, options?, control?)` returns one `JoinResult`: `{participant, activity, kind,
+  participantCount, observation?}`. `participant` is a handle, not a string. `takeover: true` reclaims
+  a standing name; fresh/departed names join normally. There is no separate `Participant.join()`
+  or public `takeover()` API. `participantCount` counts known joined-or-done names.
+- A Square owns its connection unless `resources: createSquareResourceOwner()` lends it one.
+  Closing a borrowing handle leaves that owner open. Request signals never become the borrowed
+  connection's lifetime. The MCP server drains cancelled/in-flight work before closing its owner;
+  explicit location overrides get independent request-owned connections.
+
+## One set of operations and defaults
+
+Square owns `history`, `status`, `participants`, `snapshot`, `stream`, and recovery observations.
+Participant owns `express`, `catch`, `listen`, `ignore`, `listening`, `hold`, `resume`, `done`;
+its `history` delegates to the same Square history operation.
+
+- Express waits while held/throttled unless `noWait: true`, for **every** caller. `ExpressResult`
+  includes the committed `activity`, `waited`, optional `delivery`, and landing-time warnings
+  (`unmatchedMentions`, `replyAuthorNotHere`). Warnings are not stored on the activity.
+- Catch returns `{activities, consumedThrough, remaining, idleExpired, status?, observation?}`.
+  Omitted/zero idle is immediate; positive idle uses the single leased quiet wait. Receipt selection,
+  ordinals, counts and terminal facts settle in the receipt transaction. Cancellation/replacement
+  releases only that waiter's lease and never consumes future activity.
+- All history callers return a `HistoryResult` object with `activities`. Default page size is ten;
+  `limit: null` explicitly requests an unbounded archive. Numeric limits must be 1–100. Contextual
+  queries still reject an implicit merged window over 100 activities; an explicit numeric limit
+  bounds it. CLI/tool schemas accept numeric limits only. History never writes receipts.
+- `participants()` returns `{participants, observation?}` and `listening()` returns
+  `{listening, observation?}`, not arrays carrying metadata.
+- Lifecycle operations keep contextual reentry/ownership policy. In particular, done retains its
+  native owner epoch fence instead of blindly joining first. Done accepts no message.
+
+Every operation accepts its final `OperationControl` (`signal`, optional typed `onProgress`).
+Listener/lifecycle operations take optional observation options before that control argument.
+
+## Optional observations, not another execution path
+
+Request `observe: true` on the **same method** when rendering needs additional facts. Each operation
+has a concrete optional observation type, without conditional generics or a generic outcome wrapper.
+Data-only calls do not hydrate join history, the pre-expression feed, catch presence enrichment,
+or history/status presentation annotations.
+
+Express captures its optional directed feed before the attempt and returns count/held/time facts
+from the committed transaction. Listener and lifecycle observations likewise use their mutation's
+facts, with no postcommit context read. Join uses its mutation's essential facts and treats optional
+entry/history enrichment as best-effort: `observation.enrichmentUnavailable` is explicit and the
+successful receipt survives. Catch preserves its committed page even if optional nearby presence
+fails. A cancellation or failed clock after commit cannot turn these receipts into an unsent retry.
+
+`OperationError.operation` supplements authoritative error facts with caller/filter/recipient and
+express certainty. Selected-row/execution failures remain unknown unless admission proved the
+expression unsent. CLI saves raw drafts even when opening the resource fails; its initial open
+receives the express abort signal, while recovery reopening is deliberately uncancelled.
+
+## Adapters and standalone functions
+
+CLI and tools only adapt input, identity, resource lifetime and output. They do not import private
+actions, storage, admission, scanners or query execution. MCP/Pi use the shared `square-tools.ts`
+definitions. Join JSON contains `participant.name` and the receipt fields, never the handle or its
+resources. Express wire output omits the internal delivery diagnostic as before.
+
+`discover(input, options?, control?)`, `inbox(input, sessionId, options?, control?)`,
+`diagnoseSquare(input, control?)`, and `migrateSquare(input, control?)` are ordinary public exports.
+They are not methods on a synthetic cross-square object. Diagnose/migrate resolve a path without
+opening a valid current-format Square first.
+
+## Deliberate migration breaks
+
+The independent `createSquareApplication` API, its options/results/aliases, and `square-application.ts`
+are deleted. Consumers must open/close an actual Square and select a Participant. SDK joins must use
+`(await square.join(name)).participant`; history callers must use `.activities` and opt into full
+archive reads with `limit: null`. SDK express now waits by default. MCP constructor configuration
+uses `path`, consistent with `Square.at`, rather than `squarePath`.
+
+External consumers must migrate before taking this source version. Editing source does not update
+an installed plugin, build, or running extension.

package/package.json

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

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

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

package/plugins/claude/skills/square/SKILL.md

@@ -37,9 +37,9 @@ I disagree — the cache is the wrong layer for this.
 
 **Reach.** Every activity chooses who it is meant for:
 
-- **Mention** participants to address them. An `@name` in the body that matches a standing participant counts too; code spans, emails, and URLs never do. Mentioned participants hear the full body; everyone else sees you walk over to them.
-- **Reply** to an activity to reach its author the same way.
-- **Ring the bell** only when every participant needs it.
+- **Mention** participants to address them. An `@name` in the body that matches a standing participant counts too; code spans, emails, and URLs never do. Unmatched names stay literal, with a notice to you. Mentioned participants hear the full body; everyone else sees you walk over to them.
+- **Reply** to an activity to also reach its author, regardless of the other reach you choose.
+- **Ring the bell** only when every participant needs it. Body `@names` stay literal; explicit mentions cannot combine with a bell.
 - **Land it bare** when it is meant for no one in particular. Only participants listening to you receive it.
 
 Addressing is not a secrecy boundary. Everything stays readable through `history`.

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

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

package/plugins/opencode/index.ts

@@ -3,7 +3,7 @@ import { hostLedgerForEnv } from '../../registry.js';
 import { canonicalPath } from '../../canonical-path.js';
 import { openSquare } from '../../open-square.js';
 import { closeOpenSquare } from '../../open-square.js';
-import { Square } from '../../square-application.js';
+import { Square } from '../../square-api.js';
 import { connectNative, type OpenCodeNativeSession, type OpenCodeSessionCapability } from '../../packages/agent-delivery/src/opencode-native.js';
 import { observeOpenCodeContext, publishOpenCodeRoutes, receiveOpenCodePending, type OpenCodeContextMessage } from './delivery.js';
 

package/plugins/paseo/client/markdown.tsx

@@ -84,20 +84,30 @@ function parseBlocks(markdown: string): Block[] {
 
 interface SquareBlock { meta?: string; actor?: string; body: string }
 
+function parseAttributes(source: string): Record<string, string> {
+  const attributes: Record<string, string> = {};
+  for (const match of source.matchAll(/([a-z]+)="([^"]*)"/g)) {
+    attributes[match[1]!] = match[2]!.replace(/&quot;/g, '"').replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+  }
+  return attributes;
+}
+
 // A square notification is one or more <square-activity> blocks. Split them out so the
-// envelope lines become styled chrome and only the body goes through markdown.
+// envelope becomes styled chrome and only the body goes through markdown: where and which
+// activity come from tag attributes, and the first inner line is the route sentence.
 function parseSquareBlocks(text: string): SquareBlock[] {
   const blocks: SquareBlock[] = [];
-  const re = /<square-activity>\n([\s\S]*?)\n<\/square-activity>/g;
+  const re = /<square-activity([^>]*)>\n([\s\S]*?)\n<\/square-activity>/g;
   let last = 0;
   for (const match of text.matchAll(re)) {
     const index = match.index ?? 0;
     const before = text.slice(last, index).trim();
     if (before !== "") blocks.push({ body: before });
-    const inner = match[1]!;
-    const innerLines = inner.split("\n");
-    const meta = innerLines[0]?.startsWith("· ") ? innerLines.shift() : undefined;
-    const actor = innerLines[0]?.startsWith("● ") ? innerLines.shift() : undefined;
+    const attributes = parseAttributes(match[1]!);
+    const innerLines = match[2]!.split("\n");
+    const described = [attributes.square, attributes.as, attributes.id].filter((value) => value !== undefined);
+    const meta = described.length > 0 ? `· ${described.join(" · ")}` : undefined;
+    const actor = innerLines.shift();
     blocks.push({ meta, actor, body: innerLines.join("\n").trim() });
     last = index + match[0].length;
   }