@astrosheep/square 0.3.85 → 0.3.87

package/dist/views.js

@@ -18,6 +18,7 @@ export function toPublicActivity(stored) {
     return { id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor,
         ...(stored.kind === 'say' && stored.reach !== undefined ? { reach: stored.reach } : {}),
         ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}),
+        ...(stored.kind === 'say' && stored.metadata !== undefined ? { metadata: stored.metadata } : {}),
         mentions: stored.kind === 'say' ? stored.mentions ?? [] : [], ...('target' in stored ? { target: stored.target } : {}),
         ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}) };
 }
@@ -104,46 +105,34 @@ 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 resolveParticipant(square, name, control) {
-    return (await square.artifact.read((facts) => ({ name: resolveKnownName(facts, name) }), control?.signal)).value;
-}
-export async function currentParticipant(square, name, control) {
-    return (await square.artifact.read((facts) => { const p = facts.participant(name); return p?.joined ? p.name : undefined; }, control?.signal)).value;
-}
 function statuses(facts, now) {
     return coreParticipants(facts, now).filter((p) => p.state !== 'not joined').map((p) => {
         const cursor = readCursor(facts, p.name);
         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 snapshot(square, control) {
-    return (await square.artifact.read((facts) => {
-        const header = facts.header(), hold = facts.hold();
-        const names = new Map(facts.roster().map((p) => [nameKey(p.name), p.name]));
-        const receipts = new Set(facts.receiptAssignments().map((r) => JSON.stringify([r.owner, r.index])));
-        return { context: [...header.preamble, ...header.warmup].join('\n'), actCount: facts.activityCount({ kinds: NON_READ }), hardCap: header.hardCap,
-            ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
-            held: hold.active && hold.actor !== undefined ? { by: hold.actor, ...(hold.reason === undefined ? {} : { reason: hold.reason }) } : null,
-            participants: statuses(facts, square.clock()), delivered(name, id) { return receipts.has(JSON.stringify([names.get(nameKey(name)) ?? name, parseRequiredActivityId(id)])); } };
-    }, control?.signal)).value;
-}
-export async function recoveryObservation(square, name, control) {
-    return (await square.artifact.read((facts) => {
-        const known = resolveKnownName(facts, name), hold = facts.hold();
-        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();
-        const recentActivities = selectHistory(facts, {}, lastN, ['say', 'done']).activities;
-        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)) };
-    }, control?.signal)).value;
+export function snapshot(facts, now) {
+    const header = facts.header(), hold = facts.hold();
+    const names = new Map(facts.roster().map((p) => [nameKey(p.name), p.name]));
+    const receipts = new Set(facts.receiptAssignments().map((r) => JSON.stringify([r.owner, r.index])));
+    return { context: [...header.preamble, ...header.warmup].join('\n'), actCount: facts.activityCount({ kinds: NON_READ }), hardCap: header.hardCap,
+        ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
+        held: hold.active && hold.actor !== undefined ? { by: hold.actor, ...(hold.reason === undefined ? {} : { reason: hold.reason }) } : null,
+        participants: statuses(facts, now), delivered(name, id) { return receipts.has(JSON.stringify([names.get(nameKey(name)) ?? name, parseRequiredActivityId(id)])); } };
+}
+export function recoveryObservation(facts, name, now) {
+    const known = resolveKnownName(facts, name), hold = facts.hold();
+    return { participant: known, roster: rosterNames(facts), activitySummaries: unreadActivitySummaries(facts, known, now), standingCount: inSquareCount(facts), held: hold.active,
+        ...(hold.reason === undefined ? {} : { holdReason: hold.reason }), ownActivityCount: facts.participant(known).sayCount, hardCap: facts.header().hardCap };
+}
+export function entryPresentation(facts, name, lastN = HISTORY_DEFAULT_LIMIT) {
+    const header = facts.header();
+    const recentActivities = selectHistory(facts, {}, lastN, ['say', 'done']).activities;
+    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)) };
 }
 function classifyPresence(participants, now) {
     const here = participants.filter((participant) => participant.state === 'active' && (participant.presence === 'watching'
@@ -159,14 +148,12 @@ export function queryParticipants(facts, context, observe = false) {
     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) => {
-        const participants = facts.roster().filter((p) => p.joined).map((p) => {
-            const receiptAt = facts.receiptFacts(p.name, p.lastJoinIndex ?? -1).latestAt;
-            return { name: p.name, lastActiveAt: receiptAt === undefined ? p.lastActiveAt : Math.max(p.lastActiveAt ?? -Infinity, receiptAt) };
-        }).sort(compareParticipantActivity).map((p) => p.name);
-        return { context: facts.header().preamble, participants, activities: facts.activityCount({ kinds: ['say'] }) };
-    }, control?.signal)).value;
+export function listPresentation(facts) {
+    const participants = facts.roster().filter((p) => p.joined).map((p) => {
+        const receiptAt = facts.receiptFacts(p.name, p.lastJoinIndex ?? -1).latestAt;
+        return { name: p.name, lastActiveAt: receiptAt === undefined ? p.lastActiveAt : Math.max(p.lastActiveAt ?? -Infinity, receiptAt) };
+    }).sort(compareParticipantActivity).map((p) => p.name);
+    return { context: facts.header().preamble, participants, activities: facts.activityCount({ kinds: ['say'] }) };
 }
 export function queryStatus(facts, context, viewer = '', observe = false) {
     const participants = coreParticipants(facts, context.now);
@@ -204,33 +191,26 @@ export function queryStatus(facts, context, viewer = '', observe = false) {
         },
     };
 }
-export async function catchPresence(square, control) {
-    return (await square.artifact.read((facts) => {
-        const now = square.clock();
-        const participants = coreParticipants(facts, now).filter((participant) => participant.state === 'done' || participant.presence === 'watching'
-            || (participant.lastActiveAt !== undefined && now - participant.lastActiveAt <= PRESENCE_WINDOW_MS));
-        return { participants, now };
-    }, control?.signal)).value;
-}
-export async function streamProjection(square, cursor, recipient, control) {
-    return (await square.artifact.read((facts) => {
-        const page = facts.activityHeads({ afterIndex: cursor }, { edge: 'oldest', limit: PAGE_SIZE });
-        const heads = page.items.flatMap((head) => {
-            const route = recipient === undefined ? undefined : facts.directedAt(recipient, head.index)?.route;
-            return recipient !== undefined && route === undefined ? [] : [{ index: head.index, route }];
-        });
-        return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => {
-                const route = heads.find((h) => h.index === activity.index).route;
-                return { activity, ...(route === undefined ? {} : { route }) };
-            }), cursor: page.items.at(-1)?.index ?? cursor, hasMore: page.hasMore };
-    }, control?.signal)).value;
+export function catchPresence(facts, now) {
+    const participants = coreParticipants(facts, now).filter((participant) => participant.state === 'done' || participant.presence === 'watching'
+        || (participant.lastActiveAt !== undefined && now - participant.lastActiveAt <= PRESENCE_WINDOW_MS));
+    return { participants, now };
 }
-export async function streamTailProjection(square, last = HISTORY_DEFAULT_LIMIT, recipient, control) {
-    return (await square.artifact.read((facts) => {
-        if (!Number.isSafeInteger(last) || last < 0 || last > PAGE_SIZE)
-            throw new SquareError('invalid_args', `Invalid stream tail: expected a non-negative safe integer no greater than ${PAGE_SIZE}.`);
-        const heads = last === 0 ? [] : recipient === undefined ? facts.activityHeads({}, { edge: 'newest', limit: last }).items : facts.directed(recipient, {}, { edge: 'newest', limit: last }).items;
-        return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => ({ activity,
-                ...(recipient === undefined ? {} : { route: facts.directedAt(recipient, activity.index).route }) })), cursor: facts.header().lastActIndex, hasMore: false };
-    }, control?.signal)).value;
+export function streamProjection(facts, cursor, recipient) {
+    const page = facts.activityHeads({ afterIndex: cursor }, { edge: 'oldest', limit: PAGE_SIZE });
+    const heads = page.items.flatMap((head) => {
+        const route = recipient === undefined ? undefined : facts.directedAt(recipient, head.index)?.route;
+        return recipient !== undefined && route === undefined ? [] : [{ index: head.index, route }];
+    });
+    return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => {
+            const route = heads.find((h) => h.index === activity.index).route;
+            return { activity, ...(route === undefined ? {} : { route }) };
+        }), cursor: page.items.at(-1)?.index ?? cursor, hasMore: page.hasMore };
+}
+export function streamTailProjection(facts, last = HISTORY_DEFAULT_LIMIT, recipient) {
+    if (!Number.isSafeInteger(last) || last < 0 || last > PAGE_SIZE)
+        throw new SquareError('invalid_args', `Invalid stream tail: expected a non-negative safe integer no greater than ${PAGE_SIZE}.`);
+    const heads = last === 0 ? [] : recipient === undefined ? facts.activityHeads({}, { edge: 'newest', limit: last }).items : facts.directed(recipient, {}, { edge: 'newest', limit: last }).items;
+    return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => ({ activity,
+            ...(recipient === undefined ? {} : { route: facts.directedAt(recipient, activity.index).route }) })), cursor: facts.header().lastActIndex, hasMore: false };
 }

package/dist/wakes.d.ts

@@ -1,5 +1,6 @@
 import { type WatchLease, type WatchOptions } from './model.js';
-import type { OpenSquare } from './open-square.js';
+import type { SquareArtifactPort } from './ports.js';
+import type { Seat } from './model.js';
 export type WatchLeaseStart = {
     readonly type: 'started';
     readonly leaseId: string;
@@ -21,7 +22,7 @@ export type WatchLeasePulse = {
     readonly type: 'sleep';
     readonly heartbeatAt?: number;
 };
-export declare function acquireWatchLease(square: OpenSquare, name: string, leaseId: string, options: WatchOptions, signal?: AbortSignal): Promise<WatchLeaseStart>;
-export declare function pulseWatchLease(square: OpenSquare, name: string, leaseId: string, options: WatchOptions, heartbeatDue: boolean, signal?: AbortSignal): Promise<WatchLeasePulse>;
-export declare function releaseWatchLease(square: OpenSquare, name: string, leaseId: string | undefined): Promise<void>;
-export declare function ownsWatchLease(square: OpenSquare, name: string, leaseId: string, signal?: AbortSignal): Promise<boolean>;
+export declare function acquireWatchLease(artifact: SquareArtifactPort, seat: Seat, at: number, leaseId: string, options: WatchOptions, signal?: AbortSignal): Promise<WatchLeaseStart>;
+export declare function pulseWatchLease(artifact: SquareArtifactPort, seat: Seat, at: number, leaseId: string, options: WatchOptions, heartbeatDue: boolean, signal?: AbortSignal): Promise<WatchLeasePulse>;
+export declare function releaseWatchLease(artifact: SquareArtifactPort, seat: Seat, leaseId: string): Promise<void>;
+export declare function ownsWatchLease(artifact: SquareArtifactPort, seat: Seat, at: number, leaseId: string, signal?: AbortSignal): Promise<boolean>;

package/dist/wakes.js

@@ -4,23 +4,21 @@ function newLease(leaseId, at, options) {
     const filter = { ...(options.participants === undefined ? {} : { participants: [...options.participants] }), ...(options.mention === undefined ? {} : { mention: options.mention }) };
     return { leaseId, heartbeatAt: at, expiresAt: at + WATCH_STALE_MS, ...(Object.keys(filter).length === 0 ? {} : { filter }) };
 }
-export async function acquireWatchLease(square, name, leaseId, options, signal) {
-    const at = square.clock();
-    const { value } = await square.artifact.transact((facts) => {
-        const known = resolveKnownName(facts, name);
-        const existing = freshWatchLease(facts, known, at);
+export async function acquireWatchLease(artifact, seat, at, leaseId, options, signal) {
+    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)
             return { type: 'active', lease: existing };
-        facts.putLease(known, newLease(leaseId, at, options));
+        facts.putLease(known, newLease(leaseId, at, options), seat.generation);
         return { type: 'started', leaseId, replaced: existing !== undefined, heartbeatAt: at };
     }, signal);
     return value;
 }
-export async function pulseWatchLease(square, name, leaseId, options, heartbeatDue, signal) {
-    const at = square.clock();
-    const { value } = await square.artifact.transact((facts) => {
-        const known = resolveKnownName(facts, name);
-        const lease = freshWatchLease(facts, known, at);
+export async function pulseWatchLease(artifact, seat, at, leaseId, options, heartbeatDue, signal) {
+    const name = seat.participant;
+    const { value } = await artifact.transactAs({ kind: 'participant', seat }, facts => {
+        const known = resolveKnownName(facts, name), lease = freshWatchLease(facts, known, at);
         if (lease?.leaseId !== leaseId)
             return { type: 'replaced' };
         const held = facts.hold().active;
@@ -30,15 +28,20 @@ export async function pulseWatchLease(square, name, leaseId, options, heartbeatD
         const type = held ? 'held' : 'sleep';
         if (!heartbeatDue)
             return { type };
-        facts.putLease(known, newLease(leaseId, at, options));
+        facts.putLease(known, newLease(leaseId, at, options), seat.generation);
         return { type, heartbeatAt: at };
     }, signal);
     return value;
 }
-export async function releaseWatchLease(square, name, leaseId) {
-    if (leaseId !== undefined)
-        await square.artifact.transact((facts) => facts.removeLease(resolveKnownName(facts, name), leaseId));
+export async function releaseWatchLease(artifact, seat, leaseId) {
+    await artifact.transactAs({ kind: 'participant', seat }, facts => facts.removeLease(seat.participant, leaseId, seat.generation));
 }
-export async function ownsWatchLease(square, name, leaseId, signal) {
-    return (await square.artifact.read((facts) => freshWatchLease(facts, resolveKnownName(facts, name), square.clock())?.leaseId === leaseId, signal)).value;
+export async function ownsWatchLease(artifact, seat, at, leaseId, signal) {
+    const name = seat.participant;
+    return (await artifact.read(facts => {
+        const current = facts.seat(name);
+        if (current === undefined || current.generation !== seat.generation)
+            return false;
+        return freshWatchLease(facts, resolveKnownName(facts, name), at)?.leaseId === leaseId;
+    }, signal)).value;
 }

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

@@ -181,7 +181,7 @@ These are deliverer closures, not a reviewer verdict. Rows distinguish behavior
 | Packed owner orchestration hides effects/count integrity | History, lifecycle branches, maintenance/discovery/recovery, catch conflict and SDK recognize are expanded into readable steps. Remaining one-line SDK delegates are supported simple resource calls, not packed async policy. Inspect implementation diff; all new source is included in count. |
 | Invalid reply / done repair regressions | Typed `invalid_reply` covers malformed and valid-but-absent IDs; typed reach/done reasons stay domain facts, CLI owns glyphs/flags. Express-recovery tests execute printed repaired commands, preserving raw drafts, body candidates and other recipients. Unknown/landed effects offer reconciliation, never replay. |
 | Failing application clock prevents draft creation | `executeExpression` uses `saveActivityDraft`'s transport-local `Date.now` default, never the failed owner clock. Focused `express-recovery` fixture supplies a throwing clock and landed error plus throwing recovery; exact CRLF raw is already saved at recovery invocation, landed ID remains in history reconciliation, and no replay is offered. |
-| Captured default wake stops at adapter or executable selection | Amended `defaultWakeAdapters(env)` builds `CodexQueueAdapter({env})`; queue executable comes from explicit bin, else supplied env, never later ambient env. Boundary test uses a real isolated fake executable and captured child environment/queue destination after global mutation; injected port wins. No real native delivery. |
+| Captured default wake stops at adapter or executable selection | Amended `createDefaultWakeTransport(env)` builds `CodexQueueTransport({env})`; semantic state time belongs to Square operations and never controls external I/O deadlines; queue executable comes from explicit bin, else supplied env, never later ambient env. Boundary test uses a real isolated fake executable and captured child environment/queue destination after global mutation; injected port wins. No real native delivery. |
 | Force-build ignores cancellation under lock | Amended build/create signal reaches existing lock retries and transaction boundaries; abort checked before public link, cleanup signal-free, no postcommit rejection. Real exclusive-lock fixture cancels, unlocks, and proves unchanged snapshot/no delayed rebuild/no temporary artifact. Separate published-link fixture aborts after commit and still gets the build result. |
 | Removed helper tests / package contract | Obsolete consumers moved to actual application/renderer boundaries, not production stubs. Full suite includes packed ESM root import + TypeScript consumer + unsupported deep-import denial, native import migration, ownership/storage/migration and receipts. |
 

package/guides/backends.md

@@ -0,0 +1,180 @@
+# Locations and the stdio backend
+
+Square and Participant are the same public resource API for local SQLite, local in-memory,
+and stdio-backed squares. There is no separate participant policy or caller-specific dispatch.
+`Square.at` / `Square.build` choose the backend before opening storage. CLI, MCP and Pi tools use
+that same boundary. No Slack backend or external messaging integration is included.
+
+## Runnable setup
+
+From a built source checkout (`npm run build`), create a JSON configuration file, substituting
+absolute paths for this machine:
+
+```json
+{
+  "backends": {
+    "local": {
+      "command": "/absolute/path/to/node",
+      "args": ["/absolute/path/to/square/dist/stdio-server.js", "--root", "/absolute/path/to/squares"]
+    }
+  }
+}
+```
+
+The bundled backend's standalone startup command is:
+
+```sh
+node /absolute/path/to/square/dist/stdio-server.js --root /absolute/path/to/squares
+```
+
+Normally Square spawns it automatically, without a shell, using the configured command. Its
+stdin/stdout are the protocol, not an interactive terminal. Stderr is diagnostics. The client
+drains stderr without inserting it into participant output or error messages.
+
+```sh
+export SQUARE_BACKENDS_CONFIG=/absolute/path/to/backends.json
+export SQUARE_LOCATION=stdio://local/design
+printf '# Design\nA place to compare ideas.\n' | node dist/square.js build -
+node dist/square.js --as Alice join
+node dist/square.js --as Bob join
+node dist/square.js --as Alice express --force 'What do you think @Bob?'
+node dist/square.js --as Bob history
+node dist/square.js --as Bob catch --now
+```
+
+History does not consume. Catch consumes eligible directed activity once. A reply uses the usual
+`--reply act/N`; mentions, replies, listening, ownership, hold/throttle, reentry and receipt semantics
+are the existing SQLite implementation. Independent processes address the same `design.square`
+inside the backend root. They do **not** share an in-memory resource.
+
+SDK callers may provide typed configuration directly:
+
+```ts
+import { Square, type SquareBackends } from '@astrosheep/square';
+
+const backends: SquareBackends = {
+  local: { command: process.execPath, args: ['/absolute/path/to/square/dist/stdio-server.js', '--root', '/tmp/squares'] },
+};
+const square = await Square.at({ path: 'stdio://local/design', backends, participant: 'Bob' });
+try {
+  const bob = (await square.join()).participant;
+  const caught = await bob.catch();
+  console.log(caught.activities);
+} finally {
+  await square.close();
+}
+```
+
+Use the same `path` and `backends` in `createSquareMcpServer` options. Tool calls can override
+`location: "stdio://local/design"`; the override owns its process rather than borrowing the
+configured local SQLite connection. Pi tools accept the identical location and read the captured
+`SQUARE_BACKENDS_CONFIG`. Native session identity is still chosen by each adapter on each call.
+
+## Locations and configuration
+
+- Plain locations are filesystem paths, resolved against captured input `cwd`. `inMemory` is always
+  local. Remote `build` creates a square through the backend; it never writes a URI-named local file.
+- Stdio URI grammar is `stdio://<alias>/<encoded-key>`. Aliases are case-sensitive ASCII letters,
+  digits, `_` and `-`. The key is one nonempty Unicode name, **not** a hierarchy: encode it with
+  `encodeURIComponent`, decoded exactly once. Encoded slashes/backslashes, controls, `.` and `..`
+  are refused. Canonical URIs re-encode the decoded key, so `hello%20world` is unambiguous.
+  Credentials, ports, query strings, fragments, extra path segments and unknown schemes are refused.
+- A key `design` maps to `design.square` in the bundled server root. The root is created if needed;
+  resolved artifact targets outside it (including existing escaping symlinks) are refused. Use a root
+  managed by the backend owner, not an attacker-writable directory. Different aliases need not refer
+  to different servers, but ownership is established by backend persistence, not by the alias.
+- An alias is explicit configuration, never an executable in a URI. An entry is
+  `{command: string, args?: string[], cwd?: string, env?: Record<string,string>}`. `command` is a
+  program name on PATH or a path. Relative command paths, entry `cwd`, and the config-file path are
+  resolved against captured input `cwd`, **not** relative to the config file. Commands spawn with
+  no shell and inherit captured caller environment plus only the entry's explicit env overrides.
+- SDK `backends` (including `{}`) wins over file configuration. Otherwise Square reads
+  `SQUARE_BACKENDS_CONFIG`, default `~/.config/square/backends.json` (`HOME` from captured env).
+  A missing default file is harmless for local resources. Explicit missing/invalid files, malformed
+  configuration and missing selected aliases refuse with `invalid_args`. Error text never dumps
+  configuration values or environment secrets.
+- Each remote open owns one child process/connection, reused across its operations. There is no
+  global pool. A supplied SQLite `resources` owner is not used for remote opens; close still closes
+  that remote process. Separate opens share state only through the backend's persistence.
+- CLI failed-expression drafts stay in local `./drafts` for backend locations; recovery commands and
+  display labels retain the URI. Local-artifact draft placement is unchanged.
+
+## Protocol version 1
+
+Newline-delimited JSON-RPC 2.0 over UTF-8 stdin/stdout, one object per line, at most 8 MiB per frame.
+Stdout is protocol only. No batch requests. The initial versioned handshake opens one logical square
+per connection and returns an opaque handle. IDs are unique positive integers on the client;
+requests may overlap and responses may arrive out of order.
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"square/open","params":{"version":1,"key":"design","location":"stdio://local/design","identity":{"PI_SESSION_ID":"session-id"},"participant":"Bob"}}
+{"jsonrpc":"2.0","id":1,"result":{"version":1,"handle":"square"}}
+{"jsonrpc":"2.0","id":2,"method":"join","params":{"handle":"square","args":["Bob",{"observe":true}]}}
+```
+
+Open may include `build: {markdown, hardCap?, throttlePerMinute?, template?, force?}` instead of
+opening an existing artifact. The client transmits only recognized harness session coordinates,
+the Claude child flag and configured participant name as identity facts, **not the whole environment
+in the protocol**. The backend captures its own process environment, clears **all** these startup
+coordinates (including PASEO_AGENT_ID), then overlays explicit call-local facts without mutating
+`process.env`. Participant defaults remain separate from square keys. Each new tool open therefore
+uses that call's identity, not MCP/Pi/backend startup identity.
+
+After open, methods take `{handle, args, participant?}`. `args` is the public operation's positional
+arguments excluding `OperationControl`; trailing JSON nulls represent omitted optional arguments.
+Nested nulls such as `history({limit:null})` retain their public meaning.
+
+| Methods | args | participant field |
+| --- | --- | --- |
+| `participant` | `[name?]` | no; selection only, not joining |
+| `join` | `[name?, options?]` | no |
+| `history`, `status`, `participants` | `[options?]` | no |
+| `recovery` | `[name?]` | no |
+| `express` | `[body, options?]` | required |
+| `catch`, `listening`, `resume` | `[options?]` | required |
+| `listen`, `ignore`, `unlisten` | `[target, options?]` | required |
+| `hold`, `done` | `[body?, options?]` | required |
+
+Results are the concrete public operation results, including requested observations. Participant
+handles serialize as names for `participant` and `join.participant` and become real local handles
+on the client. Observation locations are canonical remote URIs and automatic delivery is false.
+Errors are JSON-RPC `{code:-32000,message,data:{code?,facts?,operation?}}`; Square codes, structured
+facts, history bounds and express certainty survive the boundary. The client does not infer
+`unsent` from a connection failure. There is no mutation retry or replay.
+
+Progress is a notification
+`{jsonrpc:"2.0",method:"square/progress",params:{id,progress}}` where progress is the typed public
+`OperationProgress`. Request abort sends `$/cancelRequest` with `{id}`; the server aborts only that
+request and returns its response **after** cleanup, including releasing a catch lease. Another
+request on the same handle continues normally. Cancellation never undoes an explicitly committed
+receipt. `square/close` with `{}` aborts/drains outstanding requests, closes SQLite and acknowledges
+with a null result. Client close is idempotent, waits briefly for graceful cleanup, then terminates
+an unresponsive process. EOF, malformed framing, version mismatch and process exit reject pending
+requests and release the connection. A lost express response after dispatch has unknown effect;
+inspect history before deciding whether to send again.
+
+## Explicit limitations
+
+- No automatic wake, route registration, native notification delivery or cross-host inbox for stdio.
+  The server disables wake dispatch and route publication explicitly, while retaining backend-local
+  session ownership. A harness identity does not imply wake capability. Use explicit `catch`
+  (including cancellable positive-idle catch) or history.
+- `snapshot` (which contains a function), `stream`, host recognition/implicit join, owner-session
+  cleanup and route-retirement operations refuse explicitly. No partial JSON snapshot or fake stream
+  is offered. Use status/participants/history and explicit participant lifecycle methods.
+- Client clock functions, host-ledger objects and wake transport objects cannot cross the process
+  boundary and are refused. Backend process configuration owns its environment, clock and ledger.
+- File doctor, migrate and discovery are local-only and refuse a selected backend URI. Run file
+  diagnostics/migration locally on the backend host with the artifact path while clients are stopped.
+  Local harness discovery/inbox do not enumerate remote backends; remote membership is not registered
+  into the client's host ledger or notification watchers.
+- No process pooling, reconnection, automatic retries, server daemon, Slack IDs, credentials, live
+  external sends, installation or release management is introduced.
+
+## Slack is a bridge, not a backend
+
+Slack never becomes a Square location and does not change the backend grammar. To bring Slack humans
+into a square, run `packages/slack-bridge` (`square-slack-bridge`) against one channel and one local
+artifact: Slack messages land as ordinary activities from `slack/<name>` participants, and Square
+`say` activities appear in the channel. The artifact stays authoritative, so mentions, replies, catch,
+notifications and previews are the existing native behavior; no core, CLI, MCP or Pi code changes.

package/guides/claude-native.md

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

package/guides/mcp.md

@@ -2,7 +2,7 @@
 
 Square provides a stdio MCP server through `square mcp-server`.
 
-Set `SQUARE_LOCATION` to the default `.square` artifact path and optionally `SQUARE_PARTICIPANT_NAME` to the default participant. Calls may override these with `location` and `as`; relative paths use the server's startup working directory. Request metadata supplies the live Codex (`threadId`) or OpenCode (`ai.opencode/sessionID`) identity when present, otherwise the startup environment is used. Participant names are not session identities.
+Set `SQUARE_LOCATION` to the default `.square` artifact path; calls may override it with `location`. Relative paths use the server's startup working directory. Join with an explicit `as` name. Later calls may omit `as` only when the artifact recognizes exactly one current name held by the call's exact Body (`channel`, `session`, optional `agent`); zero or multiple matches refuse and require explicit selection. An explicit name selects a voice but never grants custody. Request metadata supplies the live Codex (`threadId`) or OpenCode (`ai.opencode/sessionID`) coordinate when present; otherwise a reliable startup coordinate is required for participant writes. Read-only calls do not need a Body.
 
 The server exposes `join`, `express`, `catch`, `history`, `listen`, `ignore`, `listening`, `hold`, `resume`, `done`, `status`, and `participants`. `catch` consumes activities. `history` is read-only and accepts stable `act/<index>` cursors. Tool results include JSON `structuredContent` and a text representation of the same data. Square failures are returned as tool errors with a structured `{ error: { code, message, facts? } }` value.