@astrosheep/square 0.3.93 → 0.3.94

package/dist/codex-queue.js

@@ -12,7 +12,7 @@ export class CodexQueueTransport {
         const { address } = request.route;
         const threadId = address.threadId?.trim();
         if (!threadId) {
-            return { outcome: 'failed', unavailable: true, signature: 'invalid_address', message: 'Codex route has no thread id.', routeStale: true };
+            return { outcome: 'failed', signature: 'invalid_address', message: 'Codex route has no thread id.' };
         }
         const env = this.opts.env ?? process.env;
         const payload = request.artifact === undefined ? undefined
@@ -28,15 +28,15 @@ export class CodexQueueTransport {
             });
             const remaining = deadline - Date.now();
             if (remaining <= 0) {
-                return { outcome: 'failed', unavailable: true, signature: 'dispatch_budget_exhausted', message: 'The wake dispatch budget elapsed before queueing.', retainRoute: true };
+                return { outcome: 'failed', signature: 'dispatch_budget_exhausted', message: 'The wake dispatch budget elapsed before queueing.' };
             }
             await agent.queue(payload, { timeoutMs: remaining });
             return { outcome: 'accepted' };
         }
         catch (error) {
             if (error instanceof DeliveryError && error.code === 'session_inactive') {
-                return { outcome: 'failed', unavailable: true, signature: 'boundary_not_stopped',
-                    message: 'The Codex thread has no current Stop boundary for queueing.', retainRoute: true };
+                return { outcome: 'failed', signature: 'boundary_not_stopped',
+                    message: 'The Codex thread has no current Stop boundary for queueing.' };
             }
             const message = error instanceof Error ? error.message : String(error);
             if (!(error instanceof DeliveryError) || error.maybeDelivered)

package/dist/decisions.d.ts

@@ -5,21 +5,14 @@ type TimedAct<K extends Act['kind'] = Act['kind']> = Extract<Act, {
 }> & {
     at: number;
 };
-import type { ExpressResult, ParticipantSummary as ParticipantStatus, UnreadActivitySummary } from './square-facade.js';
-export type { ParticipantSummary as ParticipantStatus, ParticipantPresence as CorePresenceState, UnreadActivitySummary, UnreadActivityPreview } from './square-facade.js';
+import type { ExpressResult, ParticipantSummary, UnreadActivitySummary } from './square-facade.js';
 export declare function resolveKnownName(facts: SquareRead, name: string): string;
 export interface DecideJoinResult {
     joinedName: string;
     addParticipant: boolean;
     joinAct?: TimedAct<'join'>;
 }
-export interface DecideImplicitJoinResult {
-    joinedName: string;
-    state: 'joined' | 'active' | 'done';
-    joinAct?: TimedAct<'join'>;
-}
 export declare function decideJoin(facts: SquareRead, name: string, now: number): DecideJoinResult;
-export declare function decideImplicitJoin(facts: SquareRead, name: string, now: number): DecideImplicitJoinResult;
 export type ActDecision = ({
     type: 'sent';
     act: TimedAct;
@@ -40,7 +33,7 @@ export type ActDecision = ({
     type: 'bell_quota';
     nextAt: number;
 };
-/** Count the directed suffix, but hydrate only its last three previews per spelling. */
+/** Count the directed suffix and hydrate only its last activity by index per spelling. */
 export declare function unreadActivitySummaries(facts: SquareRead, name: string, now: number): UnreadActivitySummary[];
 export declare function decideAct(facts: SquareRead, input: {
     name: string;
@@ -61,5 +54,6 @@ export declare function coreUnlisten(facts: SquareRead, actor: string, target: s
 export declare function coreListening(facts: SquareRead, actor: string): readonly string[];
 export declare function coreHold(facts: SquareRead, actor: string, body: string, now: number): TimedAct<'hold'>;
 export declare function coreResume(facts: SquareRead, actor: string, now: number): TimedAct<'resume'>;
-export declare function compareParticipantActivity(a: Pick<ParticipantStatus, 'name' | 'lastActiveAt'>, b: Pick<ParticipantStatus, 'name' | 'lastActiveAt'>): number;
-export declare function coreParticipants(facts: SquareRead, now: number): ParticipantStatus[];
+export declare function compareParticipantActivity(a: Pick<ParticipantSummary, 'name' | 'lastActiveAt'>, b: Pick<ParticipantSummary, 'name' | 'lastActiveAt'>): number;
+export declare function coreParticipants(facts: SquareRead, now: number): ParticipantSummary[];
+export {};

package/dist/decisions.js

@@ -1,4 +1,4 @@
-import { SquareError, isSquareError, sameName, nameKey, validateName, validateActivityMetadata, activityMetadataHasContent, } from './model.js';
+import { SquareError, isSquareError, sameName, validateName, validateActivityMetadata, activityMetadataHasContent, } from './model.js';
 import { participantIdentity } from './participant-identity.js';
 import { UNREAD_BLOCK_GRACE_MS, freshWatchLease, readCursor, FACT_PAGE_SIZE, THROTTLE_WINDOW_MS } from './runtime.js';
 import { formatActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
@@ -17,12 +17,6 @@ export function decideJoin(facts, name, now) {
     return current?.joined ? { joinedName, addParticipant: false }
         : { joinedName, addParticipant: current === undefined, joinAct: { kind: 'join', actor: joinedName, at: now } };
 }
-export function decideImplicitJoin(facts, name, now) {
-    validateName(name);
-    const current = facts.participant(name);
-    return current === undefined ? { joinedName: name, state: 'joined', joinAct: { kind: 'join', actor: name, at: now } }
-        : { joinedName: current.name, state: current.joined ? 'active' : 'done' };
-}
 function validateActivityName(name) {
     try {
         validateName(name);
@@ -54,34 +48,28 @@ function requireStanding(current) {
     if (!current.joined)
         throw new SquareError('not_joined', `${participantIdentity(current.name)} has not joined this square`);
 }
-/** Count the directed suffix, but hydrate only its last three previews per spelling. */
+/** Count the directed suffix and hydrate only its last activity by index per spelling. */
 export function unreadActivitySummaries(facts, name, now) {
     let afterIndex = readCursor(facts, name);
-    const numbers = new Map();
     const summaries = new Map();
     while (true) {
         const page = facts.directed(name, { afterIndex }, { edge: 'oldest', limit: FACT_PAGE_SIZE });
         for (const item of page.items) {
-            const key = nameKey(item.actor);
-            const number = (numbers.get(key) ?? 0) + 1;
-            numbers.set(key, number);
-            const summary = summaries.get(item.actor) ?? { count: 0, latestAt: -Infinity, previews: [] };
+            const summary = summaries.get(item.actor) ?? { count: 0, latestAt: -Infinity, lastIndex: item.index };
             summary.count++;
             summary.latestAt = Math.max(summary.latestAt, item.at);
-            summary.previews.push({ index: item.index, number });
-            if (summary.previews.length > 3)
-                summary.previews.shift();
+            summary.lastIndex = item.index;
             summaries.set(item.actor, summary);
         }
         if (!page.hasMore)
             break;
         afterIndex = page.items.at(-1).index;
     }
-    const selected = facts.activities([...summaries.values()].flatMap((item) => item.previews.map((preview) => preview.index)));
+    const selected = facts.activities([...summaries.values()].map((item) => item.lastIndex));
     const byIndex = new Map(selected.map((item) => [item.index, item]));
     return [...summaries].map(([name, summary]) => ({
         name, count: summary.count, latestActivityAgeMs: Math.max(0, now - summary.latestAt),
-        previews: summary.previews.map((preview) => ({ number: preview.number, act: byIndex.get(preview.index), perception: 'full' })),
+        preview: byIndex.get(summary.lastIndex),
     })).sort((a, b) => a.latestActivityAgeMs - b.latestActivityAgeMs || a.name.localeCompare(b.name));
 }
 export function decideAct(facts, input) {
@@ -219,10 +207,11 @@ export function coreParticipants(facts, now) {
                 lastActiveAt = Math.max(lastActiveAt ?? -Infinity, seenAt);
         }
         return {
-            name: current.name, state: current.done ? 'done' : current.joined ? 'active' : 'not joined',
+            name: current.name, deliveryAvailable: facts.seat(current.name)?.wakeAddress !== undefined,
             listening: facts.attention(current.name).filter((item) => item.kind === 'listen').map((item) => item.target),
             activityCount: current.sayCount, lastActiveAt,
-            presence: current.done ? 'done' : !current.joined ? 'never-joined' : freshWatchLease(facts, current.name, now) !== undefined ? 'watching' : 'active',
+            presence: current.done ? 'done' : !current.joined ? 'never-joined' : facts.seat(current.name)?.attachment === 'detached' ? 'away'
+                : freshWatchLease(facts, current.name, now) !== undefined ? 'watching' : 'active',
             unreadActivityCount: current.joined ? facts.directedCount(current.name, { afterIndex: readCursor(facts, current.name) }) : 0,
             pendingMentionCount: current.joined ? facts.directedCount(current.name, { afterIndex: current.lastJoinIndex ?? -1, unseenOnly: true }) : 0,
         };

package/dist/delivery-deferral.js

@@ -1,4 +1,4 @@
-import { SquareError, sameBody } from './model.js';
+import { SquareError } from './model.js';
 export const MAX_DELIVERY_DEFERRAL_MS = 24 * 60 * 60 * 1000;
 export function validateMetadataMatch(value) {
     const fail = () => { throw new SquareError('invalid_args', 'Invalid metadata match.'); };
@@ -69,7 +69,7 @@ export function matchingDeferrals(deferrals, metadata, now) {
 }
 export function deliveryDeferralExpiry(facts, captured, index, now) {
     const seat = facts.seat(captured.participant);
-    if (seat === undefined || seat.generation !== captured.generation || !sameBody(seat.body, captured.body))
+    if (seat === undefined || seat.generation !== captured.generation || seat.owner !== captured.owner)
         return undefined;
     const leases = facts.deliveryDeferrals(seat.participant, seat.generation);
     if (!leases.some(lease => lease.expiresAt > now))

package/dist/delivery-health.d.ts

@@ -12,7 +12,6 @@ export interface WakeAttempt {
     readonly outcome: 'accepted' | 'unknown' | 'failed';
     readonly signature?: string;
     readonly attemptN: number;
-    readonly session?: string;
     readonly message?: string;
     readonly diagnostic?: unknown;
 }

package/dist/delivery-health.js

@@ -38,7 +38,6 @@ export async function classifyDeliveryHealth(squarePath, opts) {
                 routeKind: attemptRow.route.kind,
                 outcome: attemptRow.outcome,
                 attemptN: attemptRow.attemptN,
-                session: seat.body.session,
                 ...(attemptRow.signature === undefined ? {} : { signature: attemptRow.signature }),
                 ...(attemptRow.message === undefined ? {} : { message: attemptRow.message }),
                 ...(attemptRow.diagnostic === undefined ? {} : { diagnostic: attemptRow.diagnostic }),
@@ -128,7 +127,7 @@ function formatRelease(release, now) {
     const diagnostic = release.diagnostic === undefined ? '' : ` · ${displayField(JSON.stringify(release.diagnostic))}`;
     return `  · ${formatActivityId(release.attention.actIndex)} → ${displayField(participantIdentity(release.attention.recipient))} · ${route} · ${reason} · ${age}${message}${diagnostic}`;
 }
-function deliveryAttempt(squarePath, row, session) {
+function deliveryAttempt(squarePath, row) {
     if (row.route?.kind === undefined || row.outcome === 'released' || row.outcome === 'dispatching')
         return undefined;
     return {
@@ -137,7 +136,6 @@ function deliveryAttempt(squarePath, row, session) {
         routeKind: row.route.kind,
         outcome: row.outcome,
         attemptN: row.attemptN,
-        ...(session === undefined ? {} : { session }),
         ...(row.signature === undefined ? {} : { signature: row.signature }),
         ...(row.message === undefined ? {} : { message: row.message }),
         ...(row.diagnostic === undefined ? {} : { diagnostic: row.diagnostic }),

package/dist/delivery-operations.d.ts

@@ -1,5 +1,5 @@
-import type { SquareArtifactPort, DeliverPendingInput, DeliveryResult } from './ports.js';
-export declare function deliverPending(input: DeliverPendingInput): Promise<DeliveryResult>;
+import type { SquareArtifactPort, DeliverPendingInput } from './ports.js';
+export declare function deliverPending(input: DeliverPendingInput): Promise<void>;
 export declare function sweepPending(input: {
     readonly artifact: SquareArtifactPort;
     readonly location: string;

package/dist/delivery-operations.js

@@ -1,17 +1,15 @@
 import { randomUUID } from 'node:crypto';
 import { formatActivityId, parseActivityId } from './square-core.js';
-import { sameBody } from './model.js';
 import { pendingHead, pendingHeads, pendingRecipients, presentationBlocksWake } from './delivery.js';
 import { asSeatRef } from './seats.js';
-import { canonicalPath } from './canonical-path.js';
 import { freshWatchLease } from './runtime.js';
 import { deliveryDeferralExpiry } from './delivery-deferral.js';
 import { leaseOwnsNotification } from './delivery.js';
 function routeFor(location, seat, now) {
-    if (seat.wakeAddress === undefined)
+    if (seat.attachment !== 'attached' || seat.wakeAddress === undefined)
         return undefined;
     return {
-        location, participant: seat.participant, sessionId: seat.body.session, channel: seat.body.channel,
+        location, participant: seat.participant,
         kind: seat.wakeAddress.kind, address: { ...seat.wakeAddress.address }, updatedAt: now,
     };
 }
@@ -19,8 +17,8 @@ async function currentness(artifact, request, now) {
     const index = parseActivityId(request.activity);
     const { value } = await artifact.read((facts) => {
         const currentSeat = facts.seat(request.participant);
-        const seatCurrent = currentSeat !== undefined && currentSeat.generation === request.seat.generation
-            && sameBody(currentSeat.body, request.seat.body)
+        const seatCurrent = currentSeat !== undefined && currentSeat.attachment === 'attached' && currentSeat.generation === request.seat.generation
+            && currentSeat.owner === request.seat.owner
             && currentSeat.wakeAddress?.kind === request.route.kind
             && Object.keys(currentSeat.wakeAddress.address).length === Object.keys(request.route.address).length
             && Object.entries(currentSeat.wakeAddress.address).every(([key, val]) => request.route.address[key] === val);
@@ -59,7 +57,7 @@ async function candidates(artifact, requested, now = Date.now()) {
             : pendingRecipients(facts, requested);
         return heads.flatMap((head) => {
             const seat = facts.seat(head.recipient);
-            return seat === undefined || deliveryDeferralExpiry(facts, seat, head.index, now) !== undefined ? [] : [{ seat, head }];
+            return seat === undefined || seat.attachment !== 'attached' || deliveryDeferralExpiry(facts, seat, head.index, now) !== undefined ? [] : [{ seat, head }];
         });
     });
     return value;
@@ -81,19 +79,25 @@ function safeJson(value) {
     return String(value);
 }
 export async function deliverPending(input) {
-    const location = await canonicalPath(input.location);
+    // The resource owner supplies its identity; delivery does not interpret it as a file.
+    const location = input.location;
     const requested = input.activity === undefined ? undefined
         : typeof input.activity === 'number' ? input.activity : parseActivityId(input.activity);
     if (input.activity !== undefined && requested === undefined)
-        return { attempted: 0, accepted: 0, failed: 0, unknown: 0, notCapable: 0 };
+        return;
     const pending = await candidates(input.artifact, requested, input.now ?? Date.now());
-    let attempted = 0, accepted = 0, failed = 0, unknown = 0, notCapable = 0;
-    for (const { seat, head } of pending) {
+    // Preserve order within a receiving owner; unrelated receivers need not wait for each other.
+    const receivers = new Map();
+    for (const candidate of pending) {
+        const key = candidate.seat.owner;
+        const group = receivers.get(key) ?? [];
+        group.push(candidate);
+        receivers.set(key, group);
+    }
+    const dispatch = async ({ seat, head }) => {
         const route = routeFor(location, seat, input.now ?? Date.now());
-        if (route === undefined) {
-            notCapable += 1;
-            continue;
-        }
+        if (route === undefined)
+            return;
         const request = {
             location, participant: seat.participant, activity: formatActivityId(head.index), actor: head.actor,
             seat: asSeatRef(seat), route,
@@ -102,14 +106,11 @@ export async function deliverPending(input) {
         if (input.transport.probe !== undefined) {
             try {
                 const probe = await input.transport.probe(route);
-                if (probe === false || typeof probe === 'object' && probe.outcome === 'not-capable') {
-                    notCapable += 1;
-                    continue;
-                }
+                if (probe === false || typeof probe === 'object' && probe.outcome === 'not-capable')
+                    return;
             }
             catch {
-                notCapable += 1;
-                continue;
+                return;
             }
         }
         const claimToken = randomUUID();
@@ -117,7 +118,7 @@ export async function deliverPending(input) {
         const claim = await input.artifact.claimDelivery({ seat: request.seat, activity: request.activity, kind: 'wake',
             route: seat.wakeAddress, at: input.now ?? Date.now(), leaseMs, claimToken }).catch(() => ({ status: 'stale' }));
         if (claim.status !== 'acquired')
-            continue;
+            return;
         const withClaim = { ...request, claimToken, attemptN: claim.attemptN };
         let final;
         let suppressed = false;
@@ -138,7 +139,7 @@ export async function deliverPending(input) {
         catch { /* unverifiable */ }
         if (!before?.current) {
             await releaseClaim(input.artifact, request.seat, request.activity, claimToken, 'pre_send_revalidation_failed', before === undefined ? 'Square delivery state could not be verified.' : 'The notification is no longer current.', before);
-            continue;
+            return;
         }
         let outcome;
         try {
@@ -149,32 +150,31 @@ export async function deliverPending(input) {
         }
         if (suppressed) {
             await releaseClaim(input.artifact, request.seat, request.activity, claimToken, 'pre_send_revalidation_failed', 'The notification changed before the final send check.', final ?? { observationAvailable: false });
-            continue;
+            return;
         }
         if (outcome.outcome === 'not-capable') {
             await releaseClaim(input.artifact, request.seat, request.activity, claimToken, 'transport_not_capable', undefined, outcome.diagnostic);
-            notCapable += 1;
-            continue;
+            return;
         }
-        attempted += 1;
         const mapped = outcome.outcome === 'accepted' ? 'accepted'
             : outcome.outcome === 'unknown' ? 'unknown' : 'failed';
-        const completed = await input.artifact.completeDelivery({ seat: request.seat, activity: request.activity, claimToken,
+        await input.artifact.completeDelivery({ seat: request.seat, activity: request.activity, claimToken,
             outcome: mapped, at: Date.now(),
             ...('signature' in outcome && outcome.signature !== undefined ? { signature: outcome.signature } : {}),
             ...('message' in outcome && outcome.message !== undefined ? { message: outcome.message } : {}),
             ...('diagnostic' in outcome && outcome.diagnostic !== undefined ? { diagnostic: safeJson(outcome.diagnostic) } : {}),
         }).catch(() => false);
-        if (!completed)
-            continue;
-        if (mapped === 'accepted')
-            accepted += 1;
-        else if (mapped === 'unknown')
-            unknown += 1;
-        else
-            failed += 1;
-    }
-    return { attempted, accepted, failed, unknown, notCapable };
+    };
+    const groups = receivers.values();
+    const settled = await Promise.allSettled(Array.from({ length: Math.min(4, receivers.size) }, async () => {
+        for (const group of groups)
+            for (const candidate of group)
+                await dispatch(candidate);
+    }));
+    // Even an unexpected failure must drain siblings before the caller closes its artifact.
+    for (const result of settled)
+        if (result.status === 'rejected')
+            throw result.reason;
 }
 export async function sweepPending(input) {
     if (input.limit <= 0)

package/dist/delivery.d.ts

@@ -40,7 +40,7 @@ export declare function pendingPages(artifact: SquareArtifactPort, scan: Pending
     at: number;
     actor: string;
     recipient: string;
-    route: "bell" | "reply" | "mention" | "attention";
+    route: "bell" | "mention" | "reply" | "attention";
 }[], void, unknown>;
 /** A pass retains only its captured joins; routes and individual receipts are fresh. */
 export declare function pendingFacts(facts: SquareRead, scan: PendingScan, heads: readonly DirectedHead[]): {

package/dist/delivery.js

@@ -8,7 +8,7 @@ export function wakePreview(facts, request) {
     const head = index === undefined ? undefined : pendingHead(facts, request.participant, index);
     const item = index === undefined ? undefined : facts.activity(index);
     const seat = facts.seat(request.participant);
-    if (head === undefined || item?.kind !== 'say' || seat === undefined
+    if (head === undefined || item?.kind !== 'say' || seat === undefined || seat.attachment !== 'attached'
         || deliveryDeferralExpiry(facts, request.seat, item.index, Date.now()) !== undefined)
         return undefined;
     return renderSquareReminder([renderAttentionPreview({

package/dist/help.js

@@ -1,3 +1,4 @@
+import { JSON_COMMANDS } from './cli/json.js';
 const COMMANDS = [
     { names: ['help'], usage: 'help [command]', summary: 'Show the command index or help for one command.' },
     { names: ['version'], usage: 'version', summary: 'Print the installed version.', hiddenFromIndex: true },
@@ -52,9 +53,9 @@ const COMMANDS = [
         details: ['Options:', '  --ndjson       Emit one JSON event per line.', '  --for <name>   With --ndjson, emit notifications for one participant.', '  --last <N>     Emit the last N eligible activities first (default 10, maximum 100).', '  --after <id>   Resume after a canonical activity id (act/12).'],
     },
     {
-        names: ['inbox'], usage: 'inbox --for-session <session-id> [--limit <N>] [--json]', hiddenFromIndex: true,
+        names: ['inbox'], usage: 'inbox --for-owner <owner> [--limit <N>]', hiddenFromIndex: true,
         summary: 'Inspect a bounded machine-local notification snapshot for a native session.',
-        details: ['Options:', '  --for-session <id>  Required harness session id.', '  --limit <N>         Snapshot memberships (default 20, maximum 100).', '  --json              Emit the bounded snapshot as structured JSON.'],
+        details: ['Options:', '  --for-owner <id>    Required opaque owner.', '  --limit <N>         Snapshot memberships (default 20, maximum 100).'],
     },
     { names: ['codex-hook'], usage: '{command}', summary: 'Present pending attention at one native agent boundary.', hiddenFromIndex: true },
     { names: ['claude-mod'], usage: '{command}', summary: 'Receive a structured operation from the loaded Claude mod.', hiddenFromIndex: true },
@@ -67,7 +68,7 @@ const COMMANDS = [
     {
         names: ['participants'], usage: 'participants [--limit <count>]', usesSquare: true, group: 'host',
         summary: 'Show the participant roster and current states.',
-        details: ['Options:', '  --limit <count>  Show the first count names in roster order (default 20, maximum 100).'],
+        details: ['Options:', '  --limit <count>  Show the first count names in human text (default 20, maximum 100).'],
     },
     { names: ['hold'], usage: '--as <name> hold [reason | -]', usesSquare: true, group: 'participant', summary: 'Raise a hand and pause participant activity.' },
     { names: ['resume'], usage: '--as <name> resume', usesSquare: true, group: 'participant', summary: 'Lower the raised hand and resume activity.' },
@@ -93,7 +94,7 @@ const COMMANDS = [
     {
         names: ['migrate'], usage: 'migrate', usesSquare: true, group: 'maintenance',
         summary: 'Convert a supported older square to the current format in place.',
-        details: ['For the selected .square artifact only. Stop sessions using this artifact before conversion. Back up the stopped artifact, migrate it, then run square --location <path> doctor before starting updated clients.', 'Versions 2, 3 and 4 are accepted; version 1, unrelated or unsupported artifacts are refused without a write. Names whose own owner and route evidence agrees may share a body; names with missing or conflicting ownership stay standing without write or delivery authority. Migration reports recovered seats, unowned standing names, shared-body seats and skipped evidence. There is no --check, --backup or --force.'],
+        details: ['For the selected .square artifact only. Stop sessions using this artifact before conversion. Back up the stopped artifact, migrate it, then run square --location <path> doctor before starting updated clients.', 'Versions 2–6 migrate explicitly to format 7; format 6 attachment is preserved and Body coordinates become opaque owners. Versions 4/5 first gain attached seats; 4 also gains empty deferrals. Version 1, unrelated or unsupported artifacts refuse without a write. Names whose legacy owner and routes agree may share an owner; ambiguous names stay standing without custody. Rejoin with the same owner after migration to republish discovery. There is no --check, --backup or --force.'],
     },
 ];
 function definitionFor(command) {
@@ -117,10 +118,11 @@ export function renderGlobalHelp() {
         '',
     ]);
     return [
-        'Usage: square [--location <square>] [--as <name>] <command> [args...]',
-        'Environment: SQUARE_LOCATION sets the CLI location (local artifact path or stdio://name/key); square-accessing commands require it or --location. Use --as to select a participant.',
-        'Backends: SQUARE_BACKENDS_CONFIG selects {backends:{name:{command,args?,cwd?,env?}}}; default ~/.config/square/backends.json. See guides/backends.md.',
-        'CLI flags override environment values. Participants join explicitly; no square is joined automatically.',
+        'Usage: square [--location <square>] [--as <name>] [--owner <id>] <command> [args...]',
+        'Environment: SQUARE_LOCATION sets the CLI local artifact path; square-accessing commands require it or --location. Use --as to select a participant.',
+        'Identity: --owner overrides SQUARE_OWNER, then a complete harness identity, then user:<OS user>@<host>. Incomplete or ambiguous harness identities refuse. Owners without wake use catch --idle.',
+        'Output: --json on join, express, catch, history, listen, ignore, unlisten, listening, hold, resume, done, status, participants and inbox prints the SDK result without observation; a participant handle becomes {name}.',
+        'History emits one JSON document; stream --ndjson emits one SDK record per line.',
         '',
         ...commandLines,
         "Run 'square <command> --help' for command options.",
@@ -132,7 +134,7 @@ export function renderSubcommandHelp(command) {
     if (definition === undefined)
         return undefined;
     const aliases = definition.names.filter((name) => name !== command);
-    const usage = definition.usage.replace('{command}', command);
+    const usage = definition.usage.replace('{command}', command) + (JSON_COMMANDS.has(command) ? ' [--json]' : '');
     return [
         `Usage: square ${definition.usesSquare ? '[--location <square>] ' : ''}${usage}`,
         ...(aliases.length > 0 ? [`Aliases: ${aliases.join(', ')}`] : []),
@@ -151,7 +153,7 @@ export function helpRequest(rawArgs) {
     const args = [];
     for (let index = 0; index < rawArgs.length; index++) {
         const arg = rawArgs[index];
-        if (arg === '--location' || arg === '--as') {
+        if (arg === '--location' || arg === '--as' || arg === '--owner') {
             const value = rawArgs[index + 1];
             if (value === undefined || value.startsWith('--'))
                 return undefined;

package/dist/inbox.d.ts

@@ -1,4 +1,4 @@
-import { type Body, type LocatedSeat, type PendingMembership } from './model.js';
+import { type Owner, type LocatedSeat, type PendingMembership } from './model.js';
 import type { SquareRead } from './ports.js';
 export interface PendingWaitOptions {
     signal?: AbortSignal;
@@ -14,15 +14,12 @@ export declare function pendingAtBoundary(inbox: readonly PendingMembership[]):
 export declare function projectBoundaryEligibility(inbox: readonly PendingMembership[]): Promise<PendingMembership[]>;
 export interface SessionBindingCandidate {
     readonly location: string;
-    readonly body: Body;
+    readonly owner: Owner;
 }
 /** HOME is a candidate path index; current seats and delivery evidence live in the artifact. */
 export declare function projectSessionCandidates(input: SessionSeatQuery): Promise<readonly SessionBindingCandidate[]>;
 export interface SessionSeatQuery {
-    readonly body?: Body;
-    readonly sessionId?: string;
-    readonly channel?: string;
-    readonly agent?: string;
+    readonly owner?: Owner;
     readonly location?: string;
     readonly env?: NodeJS.ProcessEnv;
 }
@@ -36,31 +33,21 @@ export interface NativePendingPreview {
 }
 export type NativePendingPreviewInput = {
     readonly location: string;
-    readonly sessionId: string;
+    readonly generation: import('./model.js').ActivityId;
     readonly participant: string;
     readonly actIndex: number;
     readonly cancelledThrough?: number;
     readonly now: number;
 } & ({
     readonly routeKind: 'claude-native';
-    readonly address: {
-        readonly endpoint: string;
-    };
+    readonly address: Readonly<Record<string, string>>;
 } | {
     readonly routeKind: 'opencode-server';
-    readonly address: {
-        readonly sessionId: string;
-    };
+    readonly address: Readonly<Record<string, string>>;
 });
-/** First matching current seat, exact body/generation/address and catch ownership. */
+/** Current-generation native attention, owned by its exact wake address and catch state. */
 export declare function nativePendingPreview(facts: SquareRead, input: NativePendingPreviewInput): NativePendingPreview | undefined;
-export interface SessionIdentityQuery {
-    readonly channel: string;
-    readonly session: string;
-    readonly allAgents?: true;
-}
-export type SessionIdentity = Body | SessionIdentityQuery;
-export declare function sessionInbox(identity: SessionIdentity, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<PendingMembership[]>;
+export declare function sessionInbox(owner: Owner, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<PendingMembership[]>;
 export interface SessionPendingObserver {
     /** Read committed revisions before reusing content; filesystem hints are only for waiting. */
     read(options?: Pick<PendingWaitOptions, 'signal' | 'excludeKeys'>): Promise<PendingMembership[]>;
@@ -68,4 +55,4 @@ export interface SessionPendingObserver {
     close(): void;
 }
 /** Session-scoped projection over process-shared storage change detectors. */
-export declare function observeSessionPending(identity: SessionIdentity, suppliedEnv?: NodeJS.ProcessEnv): Promise<SessionPendingObserver>;
+export declare function observeSessionPending(owner: Owner, suppliedEnv?: NodeJS.ProcessEnv): Promise<SessionPendingObserver>;