@astrosheep/square 0.3.45 → 0.3.47

package/dist/catch-decisions.js

@@ -1,5 +1,6 @@
-import { audienceOf, formatActivityId, replayLandedAudiences } from './square-core.js';
-import { matchesMentionTarget, observationFor, readCursor, recordObservation } from './runtime.js';
+import { audienceOf, formatActivityId, parseActivityId } from './square-core.js';
+import { derivePerceptionProjection } from './perception-projection.js';
+import { matchesMentionTarget, recordObservation } from './runtime.js';
 import { participantIdentity } from './participant-identity.js';
 import { SquareError, sameName, validateName } from './model.js';
 import { resolveRosterName } from './runtime.js';
@@ -12,15 +13,6 @@ function catchLimit(value) {
     }
     return limit;
 }
-function defaultProjection(state) {
-    const landed = replayLandedAudiences(state.acts);
-    return {
-        cursorFor: (name) => readCursor(state, name, landed),
-        directedTo: (activity, name) => activity.kind === 'say' && landed.includes(activity, name),
-        perceive: (activity, name) => activity.kind !== 'say' || sameName(activity.actor, name) || landed.includes(activity, name) ? 'full' : 'presence',
-        isSeen: (name, index) => observationFor(state, name, index)?.state === 'seen',
-    };
-}
 function resolveCatchName(state, requestedName) {
     validateName(requestedName);
     const known = resolveRosterName(state, requestedName);
@@ -30,10 +22,33 @@ function resolveCatchName(state, requestedName) {
     return known;
 }
 /** Pure catch selection and acknowledgement over one SquareState snapshot. */
-export function decideCatch(state, requestedName, options, at, project = defaultProjection) {
+export function decideCatch(state, requestedName, options, at, project = derivePerceptionProjection) {
     const viewer = resolveCatchName(state, requestedName);
     const limit = catchLimit(options.limit);
     const delivery = project(state);
+    if (options.id !== undefined) {
+        if (['idle', 'from', 'mention', 'limit'].some((key) => Object.hasOwn(options, key))) {
+            throw new SquareError('invalid_args', 'Catch id cannot be combined with idle, from, mention or limit.');
+        }
+        const index = parseActivityId(options.id);
+        if (index === undefined)
+            throw new SquareError('invalid_args', 'Invalid catch id: expected an activity id like act/12.');
+        const activity = state.acts.find((item) => item.index === index);
+        if (activity === undefined || activity.kind !== 'say' || !delivery.directedTo(activity, viewer)) {
+            throw new SquareError('invalid_args', 'That activity is not available to catch.');
+        }
+        const perception = delivery.perceive(activity, viewer);
+        const changed = recordObservation(state, viewer, index, 'seen', at);
+        const cursor = delivery.cursorFor(viewer);
+        return {
+            viewer,
+            delivered: [activity],
+            perceptions: new Map([[index, perception]]),
+            consumedThrough: cursor < 0 ? null : formatActivityId(cursor),
+            changed,
+            remaining: state.acts.filter((item) => item.kind === 'say' && delivery.directedTo(item, viewer) && !delivery.isSeen(viewer, item.index)).length,
+        };
+    }
     const from = options.from;
     const mentionOnly = options.mention === true;
     const delivered = [];

package/dist/cli/observation-commands.js

@@ -86,12 +86,22 @@ export const catchCommand = {
         const name = requireParticipant(context.name);
         let idleMs;
         let mention;
-        let limit = CATCH_DEFAULT_LIMIT;
+        let limit;
+        let id;
         let replace = false;
         let now = false;
         const participants = [];
         for (let index = 0; index < argv.length; index++) {
-            if (argv[index] === '--from') {
+            if (argv[index] === '--id') {
+                if (id !== undefined)
+                    fail('✕ catch accepts one --id\n» square catch --help');
+                const value = requireValue(argv, index, '--id');
+                if (parseActivityId(value) === undefined)
+                    fail('✕ invalid --id: expected an activity id like act/12\n» square catch --help');
+                id = value;
+                index += 1;
+            }
+            else if (argv[index] === '--from') {
                 participants.push(...parseNameList(requireValue(argv, index, argv[index]), argv[index]));
                 index += 1;
             }
@@ -113,6 +123,12 @@ export const catchCommand = {
             else
                 fail(`✕ catch does not know ${argv[index]}\n» square catch --help`);
         }
+        if (id !== undefined) {
+            if (argv.some((flag) => ['--idle', '--from', '--mention', '--limit', '--replace'].includes(flag))) {
+                fail('✕ --id cannot be combined with --idle, --from, --mention, --limit or --replace\n» square catch --help');
+            }
+            return { id, now: true };
+        }
         if (now === (idleMs !== undefined))
             fail('catch requires exactly one mode: --now or --idle <duration>.');
         if (replace && now)
@@ -120,7 +136,7 @@ export const catchCommand = {
         return {
             ...(participants.length > 0 ? { participants } : {}),
             ...(mention === undefined ? {} : { mention }),
-            limit,
+            limit: limit ?? CATCH_DEFAULT_LIMIT,
             ...(idleMs === undefined ? {} : { idleMs }),
             ...(replace ? { replace } : {}),
             ...(now ? { now } : {}),

package/dist/cli/square-commands.js

@@ -147,6 +147,8 @@ export const joinCommand = {
                     : `✓ you banished the original ${participantIdentity(joinedName)} — the name is yours`;
             const output = [
                 entryLine,
+                '',
+                "Don't treat Square as a public dumping ground. Speak here only when you genuinely think someone else needs to know; otherwise you are needlessly interrupting them.",
                 ...(reconnect || scene === '' ? [] : ['', scene]),
                 ...(isRejoin || contextText === '' ? [] : ['', 'context', contextText]),
                 ...(isRejoin || activities === '' ? [] : ['', 'recent activity', activities]),

package/dist/delivery.js

@@ -1,6 +1,7 @@
 import { findParticipantName, sameName, } from './model.js';
 import { audienceOf, formatActivityId, replayLandedAudiences } from './square-core.js';
-import { matchesMentionTarget, readCursor, recordObservation } from './runtime.js';
+import { derivePerceptionProjection } from './perception-projection.js';
+import { matchesMentionTarget, recordObservation } from './runtime.js';
 export function notificationMessageId(squarePath, actIndex) {
     return `square:${squarePath}#${formatActivityId(actIndex)}`;
 }
@@ -13,16 +14,13 @@ export function isActivitySeen(squareState, name, actOrIndex) {
  */
 export function deriveDeliveryModel(squareState) {
     const landed = replayLandedAudiences(squareState.acts);
+    const perception = derivePerceptionProjection(squareState, landed);
     const roster = [...landed.joined];
     const plannedByIndex = new Map();
     let pendingByRecipient;
-    function canonicalRecipient(name) {
-        return landed.resolveParticipant(name) ?? name;
-    }
     function isSeen(requestedRecipient, actOrIndex) {
-        const recipient = canonicalRecipient(requestedRecipient);
         const index = typeof actOrIndex === 'number' ? actOrIndex : actOrIndex.index;
-        return squareState.runtime.observations?.[recipient]?.[formatActivityId(index)]?.state === 'seen';
+        return perception.isSeen(requestedRecipient, index);
     }
     function plan(item) {
         if (item.kind !== 'say')
@@ -64,25 +62,17 @@ export function deriveDeliveryModel(squareState) {
         }
         return [...(pendingByRecipient.get(recipient) ?? [])];
     }
-    function directedTo(item, recipient) {
-        return item.kind === 'say' && landed.includes(item, recipient);
-    }
-    function perceive(item, viewer) {
-        if (item.kind !== 'say' || sameName(item.actor, viewer))
-            return 'full';
-        return directedTo(item, viewer) ? 'full' : 'presence';
-    }
     return {
         plan,
         pendingFor,
-        directedTo,
-        perceive,
-        cursorFor: (recipient) => readCursor(squareState, recipient, landed),
+        directedTo: perception.directedTo,
+        perceive: perception.perceive,
+        cursorFor: perception.cursorFor,
         isSeen,
         knownParticipant: (name) => landed.resolveParticipant(name),
         participants: () => landed.participants,
         joinedRecipients: () => roster,
-        replayedActivityCount: landed.replayedActivityCount,
+        replayedActivityCount: perception.replayedActivityCount,
     };
 }
 export function planActNotifications(squareState, item, delivery = deriveDeliveryModel(squareState)) {

package/dist/help.js

@@ -24,9 +24,9 @@ const COMMANDS = [
     { names: ['ignore'], usage: '--as <name> ignore <participant>', usesSquare: true, group: 'participant', summary: 'Ignore one participant\'s future mentions and bare says.' },
     { names: ['listening'], usage: '--as <name> listening', usesSquare: true, group: 'participant', summary: 'Show who you are turned toward.', details: ['Listening is future-only: the edge is fixed when a say lands; it never rewrites history.'] },
     {
-        names: ['catch'], usage: '--as <name> catch (--now | --idle <duration>) [--from <names>] [--mention] [--limit <count>] [--replace]', usesSquare: true, group: 'participant',
+        names: ['catch'], usage: '--as <name> catch (--id <activity-id> [--now] | --now | --idle <duration>) [--from <names>] [--mention] [--limit <count>] [--replace]', usesSquare: true, group: 'participant',
         summary: 'Catch directed conversation since you last looked.',
-        details: ['Modes:', '  --now             Catch up immediately.', '  --idle <duration> Wait for something relevant, or for quiet to last this long.', '', 'Attention:', '  Mentions arrive when you are addressed; bells arrive for everyone; bare says require listen.', '  listen and ignore are future-only and fixed when each say lands.', '', 'Filters:', '  --from <names>    Match only comma-separated participants.', '  --mention         Match direct attention for your current participant (and bells).', '  --limit <count>   Return one page (default 10, maximum 100).', '', 'Recovery:', '  --replace         Replace another active catch for this participant.'],
+        details: ['Modes:', '  --id <activity-id> Catch exactly one activity addressed to you, with its full body; implies --now.', '                    Marks only this activity seen; repeats return it again. No filters, limit, idle or replace.', '                    history stays read-only; catch --id consumes the selected activity.', '  --now             Catch up immediately.', '  --idle <duration> Wait for something relevant, or for quiet to last this long.', '', 'Attention:', '  Mentions arrive when you are addressed; bells arrive for everyone; bare says require listen.', '  listen and ignore are future-only and fixed when each say lands.', '', 'Filters:', '  --from <names>    Match only comma-separated participants.', '  --mention         Match direct attention for your current participant (and bells).', '  --limit <count>   Return one page (default 10, maximum 100).', '', 'Recovery:', '  --replace         Replace another active catch for this participant.'],
     },
     { names: ['done'], usage: '--as <name> done [final | -]', usesSquare: true, group: 'participant', summary: 'Step out, optionally leaving a final note.' },
     {
@@ -70,7 +70,7 @@ const COMMANDS = [
     },
     {
         names: ['doctor'], usage: 'doctor', usesSquare: true, group: 'maintenance',
-        summary: 'Validate binary artifact integrity.',
+        summary: 'Validate artifact integrity.',
     },
 ];
 function definitionFor(command) {

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

@@ -2,11 +2,24 @@ import { promises as fs } from 'node:fs';
 import fsSync from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { withFileLock } from './file-lock.js';
+import { withFileLock as acquireFileLock } from './file-lock.js';
 import { nameKey } from './model.js';
 import { isCurrentlyJoined } from './runtime.js';
 const LOCK = { retryMs: 10 };
 const RETENTION = 7 * 86400000;
+// Prepare before locking: lock databases and their journals are local runtime data too.
+async function withFileLock(file, options, fn) {
+    const directory = path.dirname(file);
+    await fs.mkdir(directory, { recursive: true });
+    try {
+        await fs.writeFile(path.join(directory, '.gitignore'), '*\n', { flag: 'wx' });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    return acquireFileLock(file, options, fn);
+}
 async function canon(value) { const absolute = path.resolve(value); try {
     return await fs.realpath(absolute);
 }

package/dist/model.d.ts

@@ -1,4 +1,4 @@
-import type { Act } from './square-core.js';
+import type { Act, ActivityId } from './square-core.js';
 export { formatActivityId, parseActivityId } from './square-core.js';
 export type { Act, ActivityId, Audience, Reach } from './square-core.js';
 export declare const WAKE_ROUTE_KINDS: readonly ["opencode-server", "codex-queue", "claude-native", "pi-extension", "paseo"];
@@ -108,6 +108,7 @@ export interface ActivitiesOptions {
     json?: boolean;
 }
 export interface WatchOptions {
+    id?: ActivityId;
     participants?: string[];
     mention?: string;
     limit?: number;

package/dist/participant-host.d.ts

@@ -0,0 +1,19 @@
+import type { HostLedgerPort, PresenceChannel, SquareArtifactPort } from './ports.js';
+import { type WakeRoute } from './routes.js';
+export interface HostContext {
+    readonly artifact: SquareArtifactPort;
+    readonly clock: () => number;
+    readonly location?: string;
+    readonly hostLedger?: HostLedgerPort;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export declare function processIdentity(env: NodeJS.ProcessEnv): {
+    session: string;
+    channel: PresenceChannel;
+};
+export declare function identityRouteDraft(context: HostContext, participant: string): Promise<Omit<WakeRoute, 'updatedAt'> | undefined>;
+export declare function publishIdentityRoute(context: HostContext, participant: string, epoch?: number): Promise<void>;
+export declare function retireIdentityRoute(context: HostContext, participant: string, expectedEpoch?: number): Promise<void>;
+export declare function assertLiveOwner(context: HostContext, participant: string, expectedEpoch?: number): Promise<boolean>;
+/** Presence is best effort and runs only after the artifact mutation commits. */
+export declare function ensureLocalPresence(context: HostContext, participant: string, epoch?: number): Promise<void>;

package/dist/participant-host.js

@@ -0,0 +1,78 @@
+import { readParticipantOwner, sessionOwnsParticipant } from './registry.js';
+import { defaultWakeRouteCapabilities, publishWakeRoute, retireWakeRouteFromArtifact, resolvePrimaryWakeRoute, ROUTE_FRESH_MS } from './routes.js';
+export function processIdentity(env) {
+    const choices = [
+        [env.CLAUDE_CODE_SESSION_ID, 'claude-code'], [env.CODEX_THREAD_ID, 'codex'],
+        [env.OPENCODE_SESSION_ID, 'opencode'], [env.SQUARE_PI_SESSION_ID, 'pi'], [env.PASEO_AGENT_ID, 'paseo'],
+    ];
+    const found = choices.find(([session]) => session?.trim());
+    return found === undefined ? { session: `process:${process.pid}`, channel: 'unknown' } : { session: found[0].trim(), channel: found[1] };
+}
+export async function identityRouteDraft(context, participant) {
+    if (context.location === undefined || context.location === 'memory')
+        return undefined;
+    const identity = processIdentity(context.env ?? process.env);
+    const provider = identity.channel === 'claude-code' ? 'claude' : identity.channel === 'opencode' ? 'opencode' : identity.channel === 'pi' ? 'pi' : identity.channel === 'paseo' ? 'paseo' : 'codex';
+    const capabilities = context.hostLedger === undefined ? { canUse: () => false } : await defaultWakeRouteCapabilities(context.hostLedger);
+    return resolvePrimaryWakeRoute({ location: context.location, participant, sessionId: identity.session, provider }, context.env ?? process.env, capabilities);
+}
+async function currentOwnerEpoch(context, participant) {
+    if (context.location === undefined || context.location === 'memory')
+        return undefined;
+    const owner = await readParticipantOwner(context.location, participant, context.env ?? process.env);
+    return owner?.epoch;
+}
+export async function publishIdentityRoute(context, participant, epoch) {
+    const route = await identityRouteDraft(context, participant);
+    if (route === undefined)
+        return;
+    const ownerEpoch = epoch ?? await currentOwnerEpoch(context, participant);
+    await publishWakeRoute(context.artifact, { ...route, ...(ownerEpoch === undefined ? {} : { epoch: ownerEpoch }) }, { at: context.clock(), requireCurrentSession: true }).catch(() => undefined);
+}
+export async function retireIdentityRoute(context, participant, expectedEpoch) {
+    if (context.location === undefined || context.location === 'memory')
+        return;
+    const identity = processIdentity(context.env ?? process.env);
+    await retireWakeRouteFromArtifact(context.artifact, { location: context.location, participant, sessionId: identity.session }, expectedEpoch === undefined ? {} : { expectedEpoch }).catch(() => undefined);
+}
+export async function assertLiveOwner(context, participant, expectedEpoch) {
+    if (context.hostLedger === undefined || context.location === undefined || context.location === 'memory')
+        return true;
+    const identity = processIdentity(context.env ?? process.env);
+    // Library callers without a harness session are not ownership-fenced unless an epoch was supplied.
+    if (identity.channel === 'unknown' && expectedEpoch === undefined)
+        return true;
+    return sessionOwnsParticipant(context.location, participant, identity.session, context.env ?? process.env, expectedEpoch);
+}
+/** Presence is best effort and runs only after the artifact mutation commits. */
+export async function ensureLocalPresence(context, participant, epoch) {
+    if (context.hostLedger === undefined || context.location === undefined || context.location === 'memory')
+        return;
+    const identity = processIdentity(context.env ?? process.env);
+    const ownerEpoch = epoch ?? await currentOwnerEpoch(context, participant);
+    const now = context.clock();
+    // Semantic publish: an unexpired presence row already stands when it carries the same owner epoch.
+    try {
+        const existing = await context.hostLedger.listPresence({ location: context.location, participant, session: identity.session, scopes: ['local'], now });
+        if (existing.some((row) => row.channel === identity.channel
+            && now - (row.updatedAt ?? 0) < ROUTE_FRESH_MS
+            && (ownerEpoch === undefined || row.epoch === ownerEpoch)))
+            return;
+    }
+    catch { /* fall through to the best-effort ensure below */ }
+    const result = await context.hostLedger.ensurePresence({
+        location: context.location,
+        participant,
+        session: identity.session,
+        channel: identity.channel,
+        // Presence rows are host-ledger wall-time evidence; the square clock belongs to artifact activities.
+        updatedAt: Date.now(),
+        ...(ownerEpoch === undefined || ownerEpoch <= 0 ? {} : { epoch: ownerEpoch }),
+    }, 'local').catch((error) => ({
+        status: 'degraded',
+        record: { location: context.location, participant, session: identity.session, channel: identity.channel },
+        error,
+    }));
+    if (result.status === 'degraded')
+        process.stderr.write(`! host presence degraded: ${result.error instanceof Error ? result.error.message : String(result.error)}\n`);
+}

package/dist/perception-projection.d.ts

@@ -0,0 +1,15 @@
+import { type LandedAudienceReplay, type Perception } from './square-core.js';
+import { type SquareState, type StoredAct } from './model.js';
+/**
+ * The small, state-only perception surface shared by catch and delivery.
+ * Notification planning deliberately remains outside this projection.
+ */
+export interface PerceptionProjection {
+    directedTo(activity: StoredAct, name: string): boolean;
+    perceive(activity: StoredAct, name: string): Perception;
+    cursorFor(name: string): number;
+    isSeen(name: string, index: number): boolean;
+    readonly replayedActivityCount: number;
+}
+/** Build perception over one audience replay of a SquareState snapshot. */
+export declare function derivePerceptionProjection(state: SquareState, landed?: LandedAudienceReplay): PerceptionProjection;

package/dist/perception-projection.js

@@ -0,0 +1,28 @@
+import { formatActivityId, replayLandedAudiences } from './square-core.js';
+import { sameName } from './model.js';
+import { readCursor } from './runtime.js';
+/** Build perception over one audience replay of a SquareState snapshot. */
+export function derivePerceptionProjection(state, landed = replayLandedAudiences(state.acts)) {
+    function canonicalName(name) {
+        return landed.resolveParticipant(name) ?? name;
+    }
+    function directedTo(activity, name) {
+        return activity.kind === 'say' && landed.includes(activity, name);
+    }
+    function perceive(activity, name) {
+        if (activity.kind !== 'say' || sameName(activity.actor, name))
+            return 'full';
+        return directedTo(activity, name) ? 'full' : 'presence';
+    }
+    function isSeen(name, index) {
+        const recipient = canonicalName(name);
+        return state.runtime.observations?.[recipient]?.[formatActivityId(index)]?.state === 'seen';
+    }
+    return {
+        directedTo,
+        perceive,
+        cursorFor: (name) => readCursor(state, name, landed),
+        isSeen,
+        replayedActivityCount: landed.replayedActivityCount,
+    };
+}

package/dist/ports.d.ts

@@ -11,10 +11,7 @@ export interface SquareArtifactPort {
     transact<R>(fn: (state: SquareState, version: number) => {
         state?: SquareState;
         result: R;
-    } | Promise<{
-        state?: SquareState;
-        result: R;
-    }>): Promise<R>;
+    }): Promise<R>;
     changed(sinceVersion: number, timeoutMs: number): Promise<boolean>;
     close(): Promise<void>;
 }

package/dist/presence.d.ts

@@ -1,6 +1,2 @@
-import { type DeliveryModel } from './delivery.js';
-import type { OpenSquare } from './open-square.js';
-import type { CatchOptions, CatchResult } from './square-facade.js';
-export declare function catchUp(square: OpenSquare, name: string, options?: CatchOptions, deriveDelivery?: (state: import('./model.js').SquareState) => DeliveryModel): Promise<CatchResult>;
 /** Commit seen only for complete, actually rendered boundary bodies. */
 export declare function markBoundarySeen(squarePath: string, name: string, actIndexes: readonly number[], at?: number): Promise<void>;

package/dist/presence.js

@@ -1,19 +1,6 @@
-import { deriveDeliveryModel } from './delivery.js';
 import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
 import { recordObservation } from './runtime.js';
-import { catchUp as actionCatchUp } from './square-actions.js';
-function operationContext(square) {
-    return 'artifact' in square
-        ? { artifact: square.artifact, clock: square.clock, location: square.location, hostLedger: square.hostLedger, wakeTransport: square.wakeTransport, env: square.env }
-        : { artifact: square.cell, clock: square.clock };
-}
-export async function catchUp(square, name, options = {}, deriveDelivery = deriveDeliveryModel) {
-    const project = deriveDelivery === deriveDeliveryModel
-        ? undefined
-        : (state) => deriveDelivery(state);
-    return actionCatchUp(operationContext(square), name, options, project);
-}
 /** Commit seen only for complete, actually rendered boundary bodies. */
 export async function markBoundarySeen(squarePath, name, actIndexes, at = Date.now()) {
     let square;

package/dist/routes.js

@@ -94,8 +94,9 @@ function sameRouteAddress(left, right) {
 }
 function canonicalRouteLocationSync(location) {
     const absolute = path.resolve(location);
+    // Match fs.promises.realpath used by artifact and presence adapters, including Windows 8.3 aliases.
     try {
-        return fs.realpathSync(absolute);
+        return fs.realpathSync.native(absolute);
     }
     catch {
         return absolute;

package/dist/square-actions.d.ts

@@ -1,14 +1,10 @@
 import { type SquareState } from './model.js';
-import type { HostLedgerPort, SquareArtifactPort } from './ports.js';
+import type { WakeTransportPort } from './ports.js';
 import type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, OwnershipFenceOptions } from './square-facade.js';
 import { type CatchProjection } from './catch-decisions.js';
-export interface OperationContext {
-    readonly artifact: SquareArtifactPort;
-    readonly clock: () => number;
-    readonly location?: string;
-    readonly hostLedger?: HostLedgerPort;
-    readonly wakeTransport?: import('./ports.js').WakeTransportPort;
-    readonly env?: NodeJS.ProcessEnv;
+import { type HostContext } from './participant-host.js';
+export interface OperationContext extends HostContext {
+    readonly wakeTransport?: WakeTransportPort;
 }
 export type { OwnershipFenceOptions };
 export declare function catchUp(square: OperationContext, name: string, options?: CatchOptions, project?: (state: SquareState) => CatchProjection): Promise<CatchResult>;

package/dist/square-actions.js

@@ -4,89 +4,9 @@ import { isSquareError, nameKey, SquareError, validateName } from './model.js';
 import { participantIdentity } from './participant-identity.js';
 import { deliverPending } from './delivery-operations.js';
 import { decideCatch } from './catch-decisions.js';
-import { claimSessionParticipant, claimSessionTakeover, readParticipantOwner, sessionOwnsParticipant, withOwnershipClaimLock } from './registry.js';
-import { applyWakeRouteToState, defaultWakeRouteCapabilities, dropParticipantWakeRoutesFromState, dropSessionWakeRoutesFromState, publishWakeRoute, retireWakeRouteFromArtifact, resolvePrimaryWakeRoute, sessionCanEndParticipant, ROUTE_FRESH_MS } from './routes.js';
-function processIdentity(env) {
-    const choices = [
-        [env.CLAUDE_CODE_SESSION_ID, 'claude-code'], [env.CODEX_THREAD_ID, 'codex'],
-        [env.OPENCODE_SESSION_ID, 'opencode'], [env.SQUARE_PI_SESSION_ID, 'pi'], [env.PASEO_AGENT_ID, 'paseo'],
-    ];
-    const found = choices.find(([session]) => session?.trim());
-    return found === undefined ? { session: `process:${process.pid}`, channel: 'unknown' } : { session: found[0].trim(), channel: found[1] };
-}
-async function identityRouteDraft(context, participant) {
-    if (context.location === undefined || context.location === 'memory')
-        return undefined;
-    const identity = processIdentity(context.env ?? process.env);
-    const provider = identity.channel === 'claude-code' ? 'claude' : identity.channel === 'opencode' ? 'opencode' : identity.channel === 'pi' ? 'pi' : identity.channel === 'paseo' ? 'paseo' : 'codex';
-    const capabilities = context.hostLedger === undefined ? { canUse: () => false } : await defaultWakeRouteCapabilities(context.hostLedger);
-    return resolvePrimaryWakeRoute({ location: context.location, participant, sessionId: identity.session, provider }, context.env ?? process.env, capabilities);
-}
-async function currentOwnerEpoch(context, participant) {
-    if (context.location === undefined || context.location === 'memory')
-        return undefined;
-    const owner = await readParticipantOwner(context.location, participant, context.env ?? process.env);
-    return owner?.epoch;
-}
-async function publishIdentityRoute(context, participant, epoch) {
-    if (context.location === undefined || context.location === 'memory')
-        return;
-    const identity = processIdentity(context.env ?? process.env);
-    const provider = identity.channel === 'claude-code' ? 'claude' : identity.channel === 'opencode' ? 'opencode' : identity.channel === 'pi' ? 'pi' : identity.channel === 'paseo' ? 'paseo' : 'codex';
-    const capabilities = context.hostLedger === undefined ? { canUse: () => false } : await defaultWakeRouteCapabilities(context.hostLedger);
-    const route = resolvePrimaryWakeRoute({ location: context.location, participant, sessionId: identity.session, provider }, context.env ?? process.env, capabilities);
-    if (route === undefined)
-        return;
-    const ownerEpoch = epoch ?? await currentOwnerEpoch(context, participant);
-    await publishWakeRoute(context.artifact, { ...route, ...(ownerEpoch === undefined ? {} : { epoch: ownerEpoch }) }, { at: context.clock(), requireCurrentSession: true }).catch(() => undefined);
-}
-async function retireIdentityRoute(context, participant, expectedEpoch) {
-    if (context.location === undefined || context.location === 'memory')
-        return;
-    const identity = processIdentity(context.env ?? process.env);
-    await retireWakeRouteFromArtifact(context.artifact, { location: context.location, participant, sessionId: identity.session }, expectedEpoch === undefined ? {} : { expectedEpoch }).catch(() => undefined);
-}
-async function assertLiveOwner(context, participant, expectedEpoch) {
-    if (context.hostLedger === undefined || context.location === undefined || context.location === 'memory')
-        return true;
-    const identity = processIdentity(context.env ?? process.env);
-    // Library callers without a harness session are not ownership-fenced unless an epoch was supplied.
-    if (identity.channel === 'unknown' && expectedEpoch === undefined)
-        return true;
-    return sessionOwnsParticipant(context.location, participant, identity.session, context.env ?? process.env, expectedEpoch);
-}
-/** Presence is best effort and runs only after the artifact mutation commits. */
-async function ensureLocalPresence(context, participant, epoch) {
-    if (context.hostLedger === undefined || context.location === undefined || context.location === 'memory')
-        return;
-    const identity = processIdentity(context.env ?? process.env);
-    const ownerEpoch = epoch ?? await currentOwnerEpoch(context, participant);
-    const now = context.clock();
-    // Semantic publish: an unexpired presence row already stands when it carries the same owner epoch.
-    try {
-        const existing = await context.hostLedger.listPresence({ location: context.location, participant, session: identity.session, scopes: ['local'], now });
-        if (existing.some((row) => row.channel === identity.channel
-            && now - (row.updatedAt ?? 0) < ROUTE_FRESH_MS
-            && (ownerEpoch === undefined || row.epoch === ownerEpoch)))
-            return;
-    }
-    catch { /* fall through to the best-effort ensure below */ }
-    const result = await context.hostLedger.ensurePresence({
-        location: context.location,
-        participant,
-        session: identity.session,
-        channel: identity.channel,
-        // Presence rows are host-ledger wall-time evidence; the square clock belongs to artifact activities.
-        updatedAt: Date.now(),
-        ...(ownerEpoch === undefined || ownerEpoch <= 0 ? {} : { epoch: ownerEpoch }),
-    }, 'local').catch((error) => ({
-        status: 'degraded',
-        record: { location: context.location, participant, session: identity.session, channel: identity.channel },
-        error,
-    }));
-    if (result.status === 'degraded')
-        process.stderr.write(`! host presence degraded: ${result.error instanceof Error ? result.error.message : String(result.error)}\n`);
-}
+import { claimSessionParticipant, claimSessionTakeover, readParticipantOwner, withOwnershipClaimLock } from './registry.js';
+import { assertLiveOwner, ensureLocalPresence, identityRouteDraft, processIdentity, publishIdentityRoute, retireIdentityRoute } from './participant-host.js';
+import { applyWakeRouteToState, dropParticipantWakeRoutesFromState, dropSessionWakeRoutesFromState, sessionCanEndParticipant } from './routes.js';
 function exposeCaught(activity, perception) {
     if (activity.kind === 'read' || activity.actor === undefined)
         throw new Error(`Cannot expose stored activity ${formatActivityId(activity.index)}`);

package/dist/square-facade.d.ts

@@ -27,6 +27,7 @@ export interface ListenerChangeResult {
     readonly activity: Activity | null;
 }
 export interface CatchOptions {
+    readonly id?: ActivityId;
     readonly idle?: number;
     readonly from?: readonly string[];
     readonly mention?: boolean;

package/dist/square-file-adapter.js

@@ -1,17 +1,18 @@
-import fs from 'node:fs';
 import path from 'node:path';
-import { createSquareState, probeSquareFile, writeSquareSnapshot, withSquareFileLock, openSquareCell, createMemoryCell, } from './square-storage.js';
+import { createSquareState, createSquareSnapshot, probeSquareFile, writeSquareSnapshot, openSquareCell, createMemoryCell, } from './square-storage.js';
 import { InternalSquareError, SquareError, } from './model.js';
 import { closeOpenSquare } from './open-square.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 /** File-owned artifact creation for the CLI and path-backed public facade. */
 export async function createSquare(squarePath, options, snippet) {
-    await withSquareFileLock(squarePath, async () => {
-        if (await fs.promises.access(squarePath).then(() => true, () => false) && !options.force) {
-            throw new InternalSquareError('conflict', `Refusing to overwrite existing square: ${squarePath}\nPass -f to overwrite.`);
-        }
-        await writeSquareSnapshot(squarePath, await createSquareState(options, snippet));
-    });
+    const state = createSquareState(options, snippet);
+    if (options.force) {
+        await writeSquareSnapshot(squarePath, state);
+        return;
+    }
+    if (!await createSquareSnapshot(squarePath, state)) {
+        throw new InternalSquareError('conflict', `Refusing to overwrite existing square: ${squarePath}\nPass -f to overwrite.`);
+    }
 }
 function validateBuildOptions(options) {
     if (options.hardCap !== undefined && options.hardCap !== null

package/dist/square-state.d.ts

@@ -0,0 +1,6 @@
+import { type BuildOptions, type HardCap, type SquareRuntimeState, type SquareState } from './model.js';
+export declare function validateSquareState(value: unknown): SquareState;
+export declare function emptyRuntimeState(nextActIndex?: number): SquareRuntimeState;
+export declare function createSquareState(options: BuildOptions & {
+    hardCap: HardCap;
+}, snippet: string): SquareState;