@astrosheep/square 0.3.36 → 0.3.38

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

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.36",
+  "version": "0.3.38",
   "description": "Native Claude Code turn-boundary delivery for Square participants",
   "author": {
     "name": "Square"

package/claude-plugin/skills/square/SKILL.md

@@ -61,7 +61,9 @@ The ownership boundary belongs here. Does this match your read?
 EOF
 ```
 
-**Addressing.** Use `--mention <name>` (repeatable) to address participants; they hear the full body even when they are not listening, and everyone else sees you walk over to them. Use `--no-mention` to land a bare activity; `listen` opts a participant into future bare delivery. Use `--bell` only when every participant needs it. An `@name` in the body is ordinary Markdown and does not address anyone. Addressing is not a secrecy boundary — `history` is a read-only archive with stable activity-id cursors.
+**Addressing.** Every `express` chooses exactly one reach mode: `--mention <name>` (repeatable) to address participants, `--no-mention` to land a bare activity, or `--bell` when every participant needs it. Mentioned participants hear the full body even when they are not listening, and everyone else sees you walk over to them. `listen` opts a participant into future bare delivery. An `@name` in the body is ordinary Markdown and does not address anyone. Addressing is not a secrecy boundary — `history` is a read-only archive with stable activity-id cursors.
+
+Every human-CLI `express` must choose exactly one reach mode: one or more `--mention <name>` flags, `--no-mention`, or `--bell`. The CLI rejects an omitted mode and rejects combining these modes. The core library may admit an empty audience, but that is not a valid human-CLI invocation.
 
 **Discipline.** Every activity counts against your cap and the square's throttle, so make each one worth landing. Keep private progress and tool chatter out — express only when another participant needs the thought, question, or decision.
 

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

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

package/codex-plugin/hooks/hooks.json

@@ -16,8 +16,7 @@
             "type": "command",
             "command": "square codex-hook",
             "timeout": 5,
-            "statusMessage": "square-codex-hook",
-            "additionalContextLimit": 1200
+            "statusMessage": "square-codex-hook"
           }
         ]
       }

package/dist/attention-presentation.d.ts

@@ -1,5 +1,5 @@
 import type { DirectedNotificationRoute } from './model.js';
-export declare const ATTENTION_BODY_MAX = 120;
+export declare const ATTENTION_BODY_MAX = 100;
 export interface AttentionPreview {
     squarePath: string;
     actIndex: number;

package/dist/attention-presentation.js

@@ -2,7 +2,7 @@ import { homedir } from 'node:os';
 import { notificationMessageId } from './delivery.js';
 import { participantIdentity } from './presentation.js';
 import { formatActivityId } from './square-core.js';
-export const ATTENTION_BODY_MAX = 120;
+export const ATTENTION_BODY_MAX = 100;
 export function previewAttentionBody(body) {
     const compact = body.replace(/\r\n/g, '\n');
     if (compact.length <= ATTENTION_BODY_MAX)
@@ -23,6 +23,5 @@ export function renderAttentionPreview(attention) {
     return [
         `${id}: ${participantIdentity(attention.recipient)} from ${participantIdentity(attention.actor)} (${attentionKind})`,
         previewAttentionBody(normalizedBody),
-        ...(normalizedBody.length <= ATTENTION_BODY_MAX ? ['✓ shown in full'] : []),
     ].join('\n');
 }

package/dist/automatic-session.js

@@ -2,12 +2,13 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
-import { Square } from './square-wiring.js';
+import { openParticipant, Square } from './square-wiring.js';
 import { entryPresentation } from './views.js';
 import { automaticParticipant } from './participant-identity.js';
 import { SquareError } from './model.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 import { projectSessionBindings } from './square-projections.js';
+import { claimSessionParticipant, releaseSessionParticipant } from './registry.js';
 import { publishWakeRoute, retireWakeRouteFromArtifact, resolvePrimaryWakeRoute, defaultWakeRouteCapabilities } from './routes.js';
 export { automaticParticipant } from './participant-identity.js';
 const providerEnv = {
@@ -68,11 +69,15 @@ export async function automaticSessionStart(provider, sessionId, cwd, env = proc
         throw new SquareError('already_joined', `${name} is already joined by another session`);
     }
     const scopedEnv = operationEnv(provider, sessionId, env);
+    const claim = await claimSessionParticipant(squarePath, name, scopedEnv);
     const square = await Square.at({ path: squarePath, hostLedger: hostLedgerForEnv(scopedEnv), env: scopedEnv });
     try {
         const implicit = await square.implicitJoin(name);
-        if (implicit.state === 'done')
+        if (implicit.state === 'done') {
+            if (claim?.status === 'acquired')
+                await releaseSessionParticipant(squarePath, name, scopedEnv);
             return undefined;
+        }
         const route = resolvePrimaryWakeRoute({ location: squarePath, participant: name, sessionId, provider }, env, await defaultWakeRouteCapabilities(hostLedgerForEnv(env)));
         if (route !== undefined) {
             const publisher = await openSquare(squarePath, { hostLedger: hostLedgerForEnv(scopedEnv), env: scopedEnv });
@@ -87,6 +92,11 @@ export async function automaticSessionStart(provider, sessionId, cwd, env = proc
         await square.reconcileBinding();
         return undefined;
     }
+    catch (error) {
+        if (claim?.status === 'acquired')
+            await releaseSessionParticipant(squarePath, name, scopedEnv).catch(() => undefined);
+        throw error;
+    }
     finally {
         await square.close();
     }
@@ -109,11 +119,16 @@ export async function automaticSessionEnd(provider, sessionId, cwd, env = proces
     const joined = await entryPresentation(reader, binding.participant).finally(() => closeOpenSquare(reader));
     if (!joined.joined)
         return;
-    const square = await Square.at({ path: squarePath, hostLedger: hostLedgerForEnv(scopedEnv), env: scopedEnv });
+    const opened = await openParticipant({ path: squarePath, hostLedger: hostLedgerForEnv(scopedEnv), env: scopedEnv }, binding.participant);
     try {
-        const participant = await square.join(binding.participant);
-        await participant.done();
-        await square.reconcileBinding();
+        await opened.participant.done();
+        const reconciler = await openSquare(squarePath);
+        try {
+            await hostLedger.reconcileBinding({ artifact: reconciler.artifact });
+        }
+        finally {
+            await closeOpenSquare(reconciler);
+        }
         const cleanup = await openSquare(squarePath);
         try {
             await retireWakeRouteFromArtifact(cleanup.artifact, { location: squarePath, participant: binding.participant, sessionId });
@@ -123,6 +138,6 @@ export async function automaticSessionEnd(provider, sessionId, cwd, env = proces
         }
     }
     finally {
-        await square.close();
+        await opened.close();
     }
 }

package/dist/boundary-presentation.js

@@ -39,6 +39,7 @@ function renderBoundary(inbox) {
     const blocks = [];
     const complete = [];
     let omitted = 0;
+    const duplicateHint = 'ignore if you have already seen this.';
     for (const [index, entry] of queued.entries()) {
         const { membership, notification } = entry;
         const block = [
@@ -59,6 +60,7 @@ function renderBoundary(inbox) {
             ...(omittedAfter > 0
                 ? [`… ${omittedAfter} unread ${omittedAfter === 1 ? 'notification' : 'notifications'} omitted.`]
                 : []),
+            duplicateHint,
             ...footer,
         ].join('\n');
         if (prospective.length > CONTEXT_MAX) {
@@ -79,6 +81,7 @@ function renderBoundary(inbox) {
             ...(omitted > 0
                 ? [`… ${omitted} unread ${omitted === 1 ? 'notification' : 'notifications'} omitted.`]
                 : []),
+            duplicateHint,
             ...footer,
         ].join('\n'),
         complete,

package/dist/cli/square-commands.js

@@ -1,7 +1,7 @@
 import { cmdActivity } from '../activity.js';
 import { formatActivityId, formatHardCap, parseActivityId, } from '../model.js';
 import { participantCommandPrefix, participantIdentity, quoteShell, renderEventCli, renderAmbientEvent, withPathOutput, } from '../presentation.js';
-import { hasAutomaticDeliveryIdentity, lookupParticipant, recordSessionDone, } from '../registry.js';
+import { claimSessionParticipant, hasAutomaticDeliveryIdentity, lookupParticipant, recordSessionDone, } from '../registry.js';
 import { createHostLedgerPort } from '../host-ledger-file-adapter.js';
 import { projectLocalParticipantBinding, sessionIdsFromEnvironment } from '../square-projections.js';
 import { nowMs } from '../runtime.js';
@@ -108,16 +108,23 @@ export const joinCommand = {
             }
             const takeoverNeeded = isRejoin && intent.kick && !reconnect;
             const oldBindings = takeoverNeeded ? await lookupParticipant(squarePath, intent.name) : [];
-            const participant = takeoverNeeded ? await square.takeover(intent.name, oldBindings.map((binding) => binding.sessionId)) : await square.join(intent.name);
-            const joinedName = participant.name;
+            let participant;
             if (takeoverNeeded) {
                 const currentSessions = new Set(sessionIdsFromEnvironment());
+                await square.takeover(intent.name);
                 for (const binding of oldBindings) {
                     if (!currentSessions.has(binding.sessionId)) {
                         await recordSessionDone(binding.sessionId, binding.name, binding.squarePath, binding.channel).catch(() => undefined);
                     }
                 }
+                await claimSessionParticipant(squarePath, intent.name, process.env);
+                participant = await square.join(intent.name);
+            }
+            else {
+                await claimSessionParticipant(squarePath, intent.name, process.env);
+                participant = await square.join(intent.name);
             }
+            const joinedName = participant.name;
             const afterSquare = await openSquare(squarePath, { clock: nowMs });
             const after = await entryPresentation(afterSquare, joinedName, intent.lastN);
             await closeOpenSquare(afterSquare);

package/dist/delivery-operations.js

@@ -125,7 +125,7 @@ export async function deliverPending(input) {
                     continue;
                 }
                 const attemptN = attempts.reduce((highest, record) => Math.max(highest, record.attemptN ?? 0), 0) + 1;
-                const request = { location: input.location, participant: membership.recipient, activity, route: requestRoute };
+                const request = { location: input.location, participant: membership.recipient, activity, actor: notification.item.actor, route: requestRoute };
                 let outcome;
                 const claim = await input.hostLedger.claimEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', leaseMs, now: input.now });
                 if (claim.status !== 'acquired') {

package/dist/harness-claude.js

@@ -36,6 +36,9 @@ export async function installClaudePlugin(homeDir, run = runClaude) {
     const staged = stageReplacement(marketplaceRoot, (stage) => {
         const plugin = path.join(stage, 'plugins', SQUARE_IDENTITY.pluginName);
         fs.cpSync(fileURLToPath(new URL('../claude-plugin/', import.meta.url)), plugin, { recursive: true });
+        const skill = path.join(plugin, 'skills', 'square', 'SKILL.md');
+        fs.mkdirSync(path.dirname(skill), { recursive: true });
+        fs.copyFileSync(path.join(fileURLToPath(new URL('../skills/square/', import.meta.url)), 'SKILL.md'), skill);
         writeJson(path.join(stage, '.claude-plugin', 'marketplace.json'), {
             name: CLAUDE_MARKETPLACE_NAME,
             owner: { name: 'Square' },

package/dist/host-ledger-file-adapter.d.ts

@@ -1,4 +1,4 @@
-import type { HostLedgerPort, HostLedgerScope, PresenceRecord, PresenceKey, PresenceLookup, PresenceResult, EvidenceRecord, EvidenceClaim, EvidenceRelease, EvidenceLookup, EvidenceGc, ClaimResult, ReconcileBindingInput, ReconcileBindingResult, WakeDispatchClaim, WakeDispatchClaimInput, WakeDispatchReleaseInput, WakeDispatchTransitionInput, WakeAttemptLookup } from './host-ledger.js';
+import type { HostLedgerPort, HostLedgerScope, PresenceRecord, PresenceKey, PresenceLookup, PresenceResult, PresenceClaimResult, EvidenceRecord, EvidenceClaim, EvidenceRelease, EvidenceLookup, EvidenceGc, ClaimResult, ReconcileBindingInput, ReconcileBindingResult, WakeDispatchClaim, WakeDispatchClaimInput, WakeDispatchReleaseInput, WakeDispatchTransitionInput, WakeAttemptLookup } from './host-ledger.js';
 export interface HostLedgerFileAdapterOptions {
     userPath?: string;
     localPath?: string;
@@ -16,6 +16,7 @@ export declare class FileHostLedgerPort implements HostLedgerPort {
     private readonly clock;
     constructor(o?: HostLedgerFileAdapterOptions);
     private file;
+    claimPresence(i: PresenceRecord, scope?: HostLedgerScope): Promise<PresenceClaimResult>;
     ensurePresence(i: PresenceRecord, scope?: HostLedgerScope): Promise<PresenceResult>;
     removePresence(i: PresenceKey): Promise<void>;
     listPresence(i?: PresenceLookup): Promise<readonly PresenceRecord[]>;

package/dist/host-ledger-file-adapter.js

@@ -62,6 +62,22 @@ export class FileHostLedgerPort {
     clock;
     constructor(o = {}) { const testRoot = process.env.SQUARE_REGISTRY ? path.dirname(process.env.SQUARE_REGISTRY) : undefined; this.user = o.userPath ?? (testRoot ?? path.join(os.homedir(), '.square', 'host-ledger')); this.local = o.localPath ?? (testRoot ?? path.join(process.cwd(), '.square', 'host-ledger')); this.writable = o.writableScope ?? 'local'; this.readable = o.readableScopes ?? ['user', 'local']; this.claims = o.claimsPath ?? path.join(this.user, 'wake-claims.ndjsonl'); this.clock = o.now ?? Date.now; }
     file(s, f) { return path.join(s === 'user' ? this.user : this.local, `${f}.ndjsonl`); }
+    async claimPresence(i, scope = this.writable) { const location = await canon(i.location), r = { ...i, location, ...(scope === 'local' ? { route: undefined } : {}), updatedAt: i.updatedAt ?? this.clock(), v: 1 }, lock = path.join(this.user, 'presence-claim.lock'); try {
+        return await withFileLock(lock, LOCK, async () => { const candidates = []; for (const s of ['user', 'local']) {
+            for (const row of await read(this.file(s, 'presence'), this.clock(), true)) {
+                if (row.location !== location || nameKey(row.participant) !== nameKey(r.participant))
+                    continue;
+                candidates.push(s === 'user' ? row : { ...row, route: undefined });
+            }
+        } const existing = candidates.sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0))[0]; if (existing !== undefined) {
+            if (existing.session === r.session)
+                return { status: 'owned', record: existing };
+            return { status: 'busy', record: existing };
+        } const f = this.file(scope, 'presence'); await withFileLock(f + '.lock', LOCK, async () => write(f, [...(await read(f, this.clock(), true)).filter(x => k(x) !== k(r)), r])); return { status: 'acquired', record: r }; });
+    }
+    catch (error) {
+        return { status: 'degraded', record: r, error };
+    } }
     async ensurePresence(i, scope = this.writable) { const r = { ...i, location: await canon(i.location), ...(scope === 'local' ? { route: undefined } : {}), updatedAt: i.updatedAt ?? this.clock(), v: 1 }; const f = this.file(scope, 'presence'); try {
         await withFileLock(f + '.lock', LOCK, async () => write(f, [...(await read(f, this.clock(), true)).filter(x => k(x) !== k(r)), r]));
         return { status: 'ensured', record: r };

package/dist/host-ledger.d.ts

@@ -28,6 +28,17 @@ export type PresenceResult = {
     readonly record: PresenceRecord;
     readonly error: unknown;
 };
+export type PresenceClaimResult = {
+    readonly status: 'acquired' | 'owned';
+    readonly record: PresenceRecord;
+} | {
+    readonly status: 'busy';
+    readonly record: PresenceRecord;
+} | {
+    readonly status: 'degraded';
+    readonly record: PresenceRecord;
+    readonly error: unknown;
+};
 export interface EvidenceRecord {
     readonly location: string;
     readonly participant: string;
@@ -143,6 +154,7 @@ export type ReconcileBindingResult = {
     readonly error?: unknown;
 };
 export interface HostLedgerPort {
+    claimPresence(input: PresenceRecord, scope?: HostLedgerScope): Promise<PresenceClaimResult>;
     ensurePresence(input: PresenceRecord, scope?: HostLedgerScope): Promise<PresenceResult>;
     removePresence(input: PresenceKey): Promise<void>;
     listPresence(input: PresenceLookup): Promise<readonly PresenceRecord[]>;

package/dist/notifications.js

@@ -33,7 +33,7 @@ function renderWakePayload(request) {
     return [
         `<system-reminder source="square" wake="${wakeLabel(request.route.kind)}">`,
         `square: ${displayAttentionPath(request.location)}`,
-        `attention: ${request.activity} for ${request.participant}`,
+        `attention: ${request.activity} for ${request.participant} from ${request.actor}`,
         '</system-reminder>',
     ].join('\n');
 }

package/dist/ports.d.ts

@@ -1,6 +1,6 @@
 import type { InboxNotification, SquareState, StoredAct, WakeRoute, WatchLease } from './model.js';
 import type { PlannedNotification } from './delivery.js';
-export type { ClaimResult, EvidenceClaim, EvidenceRelease, EvidenceGc, EvidenceLookup, EvidenceRecord, HostLedgerPort, HostLedgerScope, PresenceKey, PresenceLookup, PresenceRecord, PresenceChannel, PresenceResult, ReconcileBindingInput as HostLedgerReconcileBindingInput, ReconcileBindingResult, } from './host-ledger.js';
+export type { ClaimResult, EvidenceClaim, EvidenceRelease, EvidenceGc, EvidenceLookup, EvidenceRecord, HostLedgerPort, HostLedgerScope, PresenceKey, PresenceLookup, PresenceRecord, PresenceClaimResult, PresenceChannel, PresenceResult, ReconcileBindingInput as HostLedgerReconcileBindingInput, ReconcileBindingResult, } from './host-ledger.js';
 import type { HostLedgerPort } from './host-ledger.js';
 /** Atomic artifact access. Never exposes framing, compression, locks, or storage schema. */
 export interface SquareArtifactPort {
@@ -30,6 +30,7 @@ export interface WakeRequest {
     readonly location: string;
     readonly participant: string;
     readonly activity: string;
+    readonly actor: string;
     readonly route: WakeRoute;
 }
 /** Executor-neutral presentation capability; intentionally separate from wake transport. */

package/dist/registry.d.ts

@@ -36,6 +36,11 @@ export type CurrentParticipantBinding = Readonly<{
     created: boolean;
     sessionId: string;
 }>;
+export declare function claimSessionParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<{
+    readonly status: 'acquired' | 'owned';
+    readonly sessionId: string;
+} | undefined>;
+export declare function releaseSessionParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<void>;
 export declare function bindCurrentParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<CurrentParticipantBinding>;
 export declare function unbindCurrentParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
 export interface RegistryPruneResult {

package/dist/registry.js

@@ -45,6 +45,24 @@ export async function localParticipantOwner(squarePath, name, env = process.env,
     return undefined; return (await lookupParticipant(squarePath, name, now, env)).find((binding) => sessionIds.has(binding.sessionId))?.sessionId; }
 export async function localParticipantName(squarePath, env = process.env) { const canonicalPath = await canonicalSquarePath(squarePath); const names = new Set((await Promise.all(localSessionIdentities(env).map(async (identity) => (await lookupSession(identity.sessionId, Date.now(), env)).filter((item) => item.squarePath === canonicalPath).map((item) => item.name)))).flat()); return names.size === 1 ? [...names][0] : undefined; }
 export function squareAssignedParticipantName(env = process.env) { return computeSquareAssignedParticipantName(env); }
+export async function claimSessionParticipant(squarePath, name, env = process.env) {
+    const identity = localSessionIdentities(env)[0];
+    if (identity === undefined)
+        return undefined;
+    const location = await canonicalSquarePath(squarePath);
+    const result = await ledger(env).claimPresence({ location, participant: name, session: identity.sessionId, channel: identity.channel, updatedAt: Date.now() }, 'local');
+    if (result.status === 'busy')
+        throw new SquareError('already_joined', `${name} is already bound to another session`);
+    if (result.status === 'degraded')
+        throw result.error;
+    return { status: result.status, sessionId: identity.sessionId };
+}
+export async function releaseSessionParticipant(squarePath, name, env = process.env) {
+    const identity = localSessionIdentities(env)[0];
+    if (identity === undefined)
+        return;
+    await ledger(env).removePresence({ location: squarePath, participant: name, session: identity.sessionId, channel: identity.channel });
+}
 export async function bindCurrentParticipant(squarePath, name, env = process.env) { if (squareAssignedParticipantName(env) !== name)
     throw new SquareError('invalid_args', `The current session is not assigned ${name}`); const sessionId = await localParticipantOwner(squarePath, name, env); if (sessionId !== undefined)
     return { created: false, sessionId }; if ((await lookupParticipant(squarePath, name, Date.now(), env)).at(0) !== undefined)

package/dist/square-actions.d.ts

@@ -17,7 +17,7 @@ export declare function join(square: OperationContext, name: string): Promise<{
     readonly activity: Activity | null;
 }>;
 /** End the standing participant and immediately let the caller reclaim the name. */
-export declare function takeover(square: OperationContext, name: string, oldSessionIds?: readonly string[]): Promise<{
+export declare function takeover(square: OperationContext, name: string): Promise<{
     readonly name: string;
     readonly activities: readonly Activity[];
 }>;

package/dist/square-actions.js

@@ -130,9 +130,8 @@ export async function join(square, name) {
     return { name: committed.name, activity: committed.stored === null ? null : exposeActivity(committed.stored) };
 }
 /** End the standing participant and immediately let the caller reclaim the name. */
-export async function takeover(square, name, oldSessionIds = []) {
+export async function takeover(square, name) {
     const now = square.clock();
-    const oldSessions = new Set(oldSessionIds);
     const committed = await square.artifact.transact((state) => {
         const joinedName = resolveKnownName(state, name);
         const done = coreDone(state, joinedName, '', now);
@@ -141,15 +140,9 @@ export async function takeover(square, name, oldSessionIds = []) {
         if (decision.joinAct === undefined)
             throw new SquareError('already_joined', `${participantIdentity(joinedName)} could not be reclaimed`);
         const storedJoin = committedActivity(storeActs(state, [decision.joinAct]), 'join');
-        const participantSessions = new Set([
-            ...oldSessions,
-            ...(state.routes ?? []).filter((route) => nameKey(route.participant) === nameKey(joinedName)).map((route) => route.sessionId),
-        ]);
-        state.routes = (state.routes ?? []).filter((route) => nameKey(route.participant) !== nameKey(joinedName) && !participantSessions.has(route.sessionId));
+        state.routes = (state.routes ?? []).filter((route) => nameKey(route.participant) !== nameKey(joinedName));
         return { state, result: { name: joinedName, stored: [storedDone, storedJoin] } };
     });
-    await ensureLocalPresence(square, committed.name);
-    await publishIdentityRoute(square, committed.name);
     return { name: committed.name, activities: committed.stored.map(exposeActivity) };
 }
 export async function implicitJoin(square, name) {

package/dist/square-wiring.d.ts

@@ -13,7 +13,7 @@ export declare class Square {
         readonly participant: Participant;
         readonly activity: Activity | null;
     }>;
-    takeover(name: string, oldSessionIds?: readonly string[]): Promise<Participant>;
+    takeover(name: string): Promise<Participant>;
     implicitJoin(name: string): Promise<{
         readonly state: 'joined' | 'active' | 'done';
         readonly participant?: Participant;

package/dist/square-wiring.js

@@ -69,8 +69,8 @@ export class Square {
         const joined = await join(this.context, name);
         return { participant: new ParticipantHandle(joined.name, this.square, this.context), activity: joined.activity };
     }
-    async takeover(name, oldSessionIds = []) {
-        const result = await takeover(this.context, name, oldSessionIds);
+    async takeover(name) {
+        const result = await takeover(this.context, name);
         return new ParticipantHandle(result.name, this.square, this.context);
     }
     async implicitJoin(name) {

package/guides/participant-ownership.md

@@ -0,0 +1,186 @@
+# Participant Ownership
+
+This document defines the ownership boundary for a participant name, a host
+session, and its wake route. It is the contract for ordinary `join`, automatic
+session startup, explicit `--kick`, and session shutdown.
+
+The central invariant is simple:
+
+> At most one live host session owns a participant name in one square.
+
+An artifact participant and a host session are related, but they are not the
+same fact. The artifact is authoritative for the participant lifecycle. The
+host ledger is authoritative for the local session binding. A wake route is
+only a callable address for an existing binding.
+
+The uniqueness key is the canonical square location plus `nameKey(name)` (the
+same normalized identity used by the artifact). Display spelling does not
+create a second participant.
+
+## Owners
+
+| Fact | Authority | May change it |
+| --- | --- | --- |
+| Participant name is known, active, or done | Square artifact (`SquareState`) | Square actions in an artifact transaction |
+| Session owns a name at a location | Host ledger presence | Registry/ledger binding operations |
+| Session can be woken | Wake route in the square artifact | Route operations after the lifecycle commit |
+| CLI or hook requested join, kick, or shutdown | CLI or host adapter input | The caller only; it does not become a new authority |
+
+No layer may use display text, a route row, or an old registry row as a
+replacement for the authoritative fact it does not own.
+
+## Call Boundaries
+
+The artifact boundary and the host boundary exchange facts, not each other's
+storage objects:
+
+- `square-core` and participant lifecycle actions decide and commit activities
+  (`join`, `done`, takeover) and artifact-owned wake routes. Their post-commit
+  presence refresh is best effort; they do not discover foreign sessions,
+  claim names, or remove another session's presence.
+- The host ledger claims and releases `(location, name, session, channel)`
+  bindings. It does not append participant activities and it does not decide
+  whether a name is active in the artifact.
+- The name claim must be an atomic compare-and-set on `(location, name)`:
+  observe-then-upsert (`listPresence` followed by `ensurePresence`) is not a
+  claim and cannot enforce the one-owner invariant under concurrency.
+- CLI and hook orchestration obtains the current session identity, sequences
+  the two boundaries, and performs exact-session cleanup. It may pass a
+  participant name and a lifecycle intent to an artifact operation; it must
+  not pass host binding rows or `oldSessionIds` into a square action.
+- Route publication and retirement write the artifact route set. A route is
+  useful only while its exact session binding is owned; route rows are not a
+  second name-ownership ledger.
+
+The intended shape is therefore `claim/verify -> artifact transaction ->
+presence/route effects`. A helper that combines those steps is an orchestration
+helper, not a square action. In particular, a `takeover(name,
+oldSessionIds)`-style API is the wrong boundary: the artifact can retire the
+active participant routes by name, while the host adapter cleans old presence
+by the exact sessions it observed.
+
+## Ordinary Join
+
+`join` is a name claim, not a reconnect heuristic.
+
+1. Validate the requested participant name.
+2. Ask the host ledger to claim the `(location, name)` binding for the current
+   session. An existing binding for another session is a hard refusal. A
+   binding that this same session already held is an idempotent reconnect. A
+   newly-created claim is provisional until the artifact check below passes.
+3. In one artifact transaction, decide and commit the participant `join`
+   activity when the name is not active. If the artifact already says that the
+   name is active, only a pre-existing binding for this exact session may
+   reconnect; release a provisional claim and refuse every other caller.
+4. After the artifact commit, ensure presence for the current session only.
+5. After presence is established, publish the current session's primary wake
+   route.
+6. Render the entry result from the committed artifact snapshot. Rendering
+   does not perform another ownership decision.
+
+If any precondition fails, no join activity, presence row, or route is created
+left behind for the refused session. A reconnect does not append another `join`
+activity.
+
+## Automatic Session Startup
+
+Automatic startup is a host adapter around the same ownership semantics. It is
+not an implicit kick and it does not get a separate exception for configured
+names.
+
+1. Derive the participant name from the provider session and environment.
+2. Attempt the host-ledger binding claim.
+3. If another session owns the name, return the coded `already_joined`
+   refusal. Do not rewrite the artifact, remove the other session, or create a
+   second binding.
+4. If the current session already owns the binding, refresh its presence and
+   route without another artifact `join`.
+5. If the name is new, commit the single artifact `join`, then establish
+   presence and route as in ordinary join.
+
+The hook boundary catches and reports this refusal according to host policy;
+the hook must not silently turn it into a takeover.
+
+## Explicit Kick
+
+`join --kick` is the only name-takeover operation. It is an explicit human
+action and must leave an observable lifecycle, not merely overwrite a ledger
+row.
+
+1. Resolve the requested name and collect the currently active bindings for
+   that name. The current session is excluded from the old-owner set only when
+   it is already the owner and this is a reconnect, not a kick.
+2. Under the artifact lock, commit two lifecycle activities as one transaction:
+   `done` for the standing participant, followed immediately by `join` for the
+   reclaimed name. If this transaction cannot commit, nothing is kicked.
+3. In the same artifact transaction, remove every route for the kicked
+   participant. The artifact operation receives only the participant name; it
+   does not receive host session rows. The new route is not published until
+   after the transaction succeeds.
+4. After the artifact commit, remove every old owner's presence from both
+   readable ledger scopes. The cleanup is keyed by the exact old session and
+   channel; never remove by participant name alone.
+5. Establish the new session's presence and publish its route.
+6. Reconcile once from the committed artifact and ledger facts. Reconciliation
+   may remove stale external rows, but it may not invent a join or undo the
+   committed takeover.
+
+The resulting history must contain `join -> done -> join`. A successful kick
+must leave no old binding and no old callable route. If external cleanup is
+temporarily unavailable, the artifact still records the kick and the cleanup
+remains retryable and session-scoped.
+
+## Session Shutdown
+
+Session shutdown is owner-scoped.
+
+1. Look up the binding by the exact session id and square location in the host
+   ledger.
+2. If no binding exists, stop without changing the artifact.
+3. If the binding exists and its participant is still active, ask the artifact
+   boundary to commit that participant's `done` activity. The artifact action
+   does not need the session id.
+4. Remove that exact session's presence in the host ledger and retire that
+   exact session's route in the artifact.
+5. Do not mark a replacement session done, even when it uses the same display
+   name. Under the invariant, such a replacement should have been rejected or
+   created through `--kick`.
+
+A shutdown arriving after a kick is an idempotent cleanup of an already-removed
+owner. It must not append a second `done` for the new owner.
+
+## Concurrency and Recovery
+
+The artifact transaction serializes participant lifecycle activities. The host
+ledger lock serializes binding rows. These locks protect different facts and
+must not be replaced with a copied sidecar or a display-level mutex.
+
+The safe ordering is:
+
+1. Claim or verify the session binding.
+2. Check the artifact state and commit its lifecycle transaction.
+3. Apply presence and route effects for the committed result.
+4. Retry or reconcile only the external effects that did not commit.
+
+An operation must never claim success from a partially completed sequence. A
+failed precondition produces no artifact mutation. A post-commit ledger or
+route failure produces a diagnosed, retryable external inconsistency while
+preserving the artifact's committed lifecycle.
+
+## Acceptance Evidence
+
+The implementation is complete only when these invariants are directly tested:
+
+- two sessions cannot concurrently own the same `(location, name)`;
+- same-session reconnect is idempotent and appends no second `join`;
+- automatic startup refuses a foreign owner and never performs a kick;
+- `join --kick` records `done -> join` atomically;
+- kick cleanup removes old presence and routes by exact session identity;
+- a kicked session's later shutdown cannot close the replacement;
+- a failed external cleanup is retryable without duplicating lifecycle
+  activities;
+- reconciliation removes stale external rows only when the artifact proves
+  the participant is no longer active.
+
+Tests should assert the authoritative facts and their ownership boundaries,
+not the order of helper calls or the wording of CLI output.

package/package.json

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

package/skills/square/SKILL.md

@@ -61,7 +61,9 @@ The ownership boundary belongs here. Does this match your read?
 EOF
 ```
 
-**Addressing.** Use `--mention <name>` (repeatable) to address participants; they hear the full body even when they are not listening, and everyone else sees you walk over to them. Use `--no-mention` to land a bare activity; `listen` opts a participant into future bare delivery. Use `--bell` only when every participant needs it. An `@name` in the body is ordinary Markdown and does not address anyone. Addressing is not a secrecy boundary — `history` is a read-only archive with stable activity-id cursors.
+**Addressing.** Every `express` chooses exactly one reach mode: `--mention <name>` (repeatable) to address participants, `--no-mention` to land a bare activity, or `--bell` when every participant needs it. Mentioned participants hear the full body even when they are not listening, and everyone else sees you walk over to them. `listen` opts a participant into future bare delivery. An `@name` in the body is ordinary Markdown and does not address anyone. Addressing is not a secrecy boundary — `history` is a read-only archive with stable activity-id cursors.
+
+Every human-CLI `express` must choose exactly one reach mode: one or more `--mention <name>` flags, `--no-mention`, or `--bell`. The CLI rejects an omitted mode and rejects combining these modes. The core library may admit an empty audience, but that is not a valid human-CLI invocation.
 
 **Discipline.** Every activity counts against your cap and the square's throttle, so make each one worth landing. Keep private progress and tool chatter out — express only when another participant needs the thought, question, or decision.