@astrosheep/square 0.3.46 → 0.3.47

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

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

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

@@ -6,6 +6,8 @@ allowed-tools: Bash(square *)
 
 # Square
 
+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.
+
 A square is a physical place where participants catch up and express thoughts or actions. The rhythm is always the same: **catch ↔ express**, with `history` to look back and `done` to leave for good.
 
 ```text
@@ -74,13 +76,16 @@ Every human-CLI `express` must choose exactly one reach mode: one or more `--men
 `catch` takes in the directed activity addressed to you since you last looked: mentions, bells, and bare activities from participants you are listening to.
 
 ```bash
+square --location <square> --as <name> catch --id act/12 # take in exactly this activity, with its full body
 square --location <square> --as <name> catch --now       # take in what is pending
 square --location <square> --as <name> catch --idle 30m  # wait until something relevant lands, or 30m of quiet
 square --location <square> --as <name> catch --now --mention       # take in pending mentions
 square --location <square> --as <name> catch --now --from <names>  # take in pending activity from named participants
 ```
 
-Every catch needs exactly one mode: `--now` or `--idle <duration>`. `--mention` and `--from` filter either mode; they do not replace it. Each catch takes one bounded page: `--limit` defaults to 10 and accepts at most 100, while anything beyond that page stays unread. Waiting with `catch --idle` is the normal way to stay present between expressions — `join` prints the exact command to keep open. Do not build a polling loop.
+`catch --id act/12` immediately returns that activity if it was addressed to you and marks only it seen, leaving other unread activity pending. Repeating it returns the same full body. It accepts optional `--now`, but not `--idle`, `--from`, `--mention`, `--limit` or `--replace`. Unlike read-only `history`, it consumes the selected activity.
+
+Without `--id`, every catch needs exactly one mode: `--now` or `--idle <duration>`. `--mention` and `--from` filter either mode; they do not replace it. Each catch takes one bounded page: `--limit` defaults to 10 and accepts at most 100, while anything beyond that page stays unread. Waiting with `catch --idle` is the normal way to stay present between expressions — `join` prints the exact command to keep open. Do not build a polling loop.
 
 ## Listen
 

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

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

package/dist/activity.js

@@ -79,14 +79,12 @@ export async function cmdActivity(squarePath, name, activity, resolveBody, opts)
             const pendingPublic = before.pendingPublic;
             const pendingRoomChanges = before.pendingRoomChanges;
             try {
-                const result = await participant.express(body, {
+                await participant.express(body, {
                     force,
                     ...(opts.mentions === undefined ? {} : { mentions: opts.mentions }),
                     ...(reach === undefined ? {} : { reach }),
                     ...(opts.reply === undefined ? {} : { reply: formatActivityId(opts.reply) }),
                 });
-                if (result.delivery?.notCapable)
-                    process.stderr.write(`! wake not-capable: ${result.delivery.notCapable}\n`);
                 const freshSquare = await openSquare(squarePath, { clock: nowMs });
                 const fresh = await activityPresentation(freshSquare, knownName).finally(() => closeOpenSquare(freshSquare));
                 const headerCount = fresh.participantCount;

package/dist/artifact.js

@@ -150,7 +150,8 @@ async function createTemporaryArtifact(squarePath) {
     }
 }
 async function syncTemporaryArtifact(temporary) {
-    const handle = await fs.promises.open(temporary, 'r');
+    // Windows FlushFileBuffers requires a writable handle; r+ never creates a missing file.
+    const handle = await fs.promises.open(temporary, 'r+');
     try {
         await handle.sync();
     }

package/dist/catch-decisions.d.ts

@@ -1,4 +1,5 @@
 import { type Perception } from './square-core.js';
+import { type PerceptionProjection } from './perception-projection.js';
 import { type SquareState, type StoredAct } from './model.js';
 import type { CatchOptions } from './square-facade.js';
 export interface CatchDecision {
@@ -11,11 +12,6 @@ export interface CatchDecision {
 }
 export declare const CATCH_DEFAULT_LIMIT = 10;
 export declare const CATCH_MAX_LIMIT = 100;
-export interface CatchProjection {
-    cursorFor(name: string): number;
-    directedTo(activity: StoredAct, name: string): boolean;
-    perceive(activity: StoredAct, name: string): Perception;
-    isSeen(name: string, index: number): boolean;
-}
+export type CatchProjection = Pick<PerceptionProjection, 'cursorFor' | 'directedTo' | 'perceive' | 'isSeen'>;
 /** Pure catch selection and acknowledgement over one SquareState snapshot. */
 export declare function decideCatch(state: SquareState, requestedName: string, options: CatchOptions, at: number, project?: (state: SquareState) => CatchProjection): CatchDecision;

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.' },
     {

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/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/watch.js

@@ -126,6 +126,7 @@ async function cmdWatchNow(squarePath, name, opts) {
     const facade = await openParticipant({ path: squarePath, clock: nowMs }, name);
     try {
         const caught = await facade.participant.catch({
+            ...(opts.id === undefined ? {} : { id: opts.id }),
             ...(opts.participants === undefined ? {} : { from: opts.participants }),
             ...(opts.mention === undefined ? {} : { mention: true }),
             ...(opts.limit === undefined ? {} : { limit: opts.limit }),

package/extensions/square-pi.js

@@ -46,15 +46,35 @@ export default function squarePiExtension(pi) {
   let retryWait;
   const present = (deliver, signal) => sessionId === undefined ? undefined : presentPendingAtBoundary(sessionId, deliver, undefined, undefined, signal);
 
-  const presentAtBoundary = (deliver) => {
+  let boundaryPending;
+  const boundaryControllers = new Set();
+  const presentAtBoundary = async (deliver) => {
+    // One slow Square operation must neither hold Pi's prompt nor accumulate
+    // another unresolved lookup on every prompt while the first unwinds.
+    if (boundaryPending !== undefined || sessionId === undefined) return undefined;
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(new Error('Pi boundary presentation timed out')), piBoundaryTimeoutMs());
-    const pending = present(deliver, controller.signal);
-    if (pending === undefined) {
+    boundaryControllers.add(controller);
+    let timer;
+    const expired = new Promise((resolve) => {
+      controller.signal.addEventListener('abort', () => resolve(undefined), { once: true });
+      timer = setTimeout(() => controller.abort(new Error('Pi boundary presentation timed out')), piBoundaryTimeoutMs());
+    });
+    try {
+      const pending = present((context) => {
+        // A lookup may finish after the deadline or after session replacement.
+        // Refuse before rendering so that late work cannot acknowledge anything.
+        controller.signal.throwIfAborted();
+        return deliver(context);
+      }, controller.signal);
+      boundaryPending = pending;
+      void pending?.finally(() => {
+        if (boundaryPending === pending) boundaryPending = undefined;
+      }).catch(() => undefined);
+      return await Promise.race([pending, expired]);
+    } finally {
       clearTimeout(timer);
-      return undefined;
+      boundaryControllers.delete(controller);
     }
-    return pending.finally(() => clearTimeout(timer));
   };
 
   const waitForSettled = (serial, signal) => {
@@ -73,6 +93,7 @@ export default function squarePiExtension(pi) {
   // A transport may keep its promise pending while Pi is shutting down or
   // replacing a session. Never make a lifecycle hook wait for that transport.
   const stopWatcher = () => {
+    for (const controller of boundaryControllers) controller.abort(new Error('Pi session ended'));
     watcherAbort?.abort();
     watcher = undefined;
     watcherAbort = undefined;

package/package.json

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

package/skills/square/SKILL.md

@@ -6,6 +6,8 @@ allowed-tools: Bash(square *)
 
 # Square
 
+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.
+
 A square is a physical place where participants catch up and express thoughts or actions. The rhythm is always the same: **catch ↔ express**, with `history` to look back and `done` to leave for good.
 
 ```text
@@ -74,13 +76,16 @@ Every human-CLI `express` must choose exactly one reach mode: one or more `--men
 `catch` takes in the directed activity addressed to you since you last looked: mentions, bells, and bare activities from participants you are listening to.
 
 ```bash
+square --location <square> --as <name> catch --id act/12 # take in exactly this activity, with its full body
 square --location <square> --as <name> catch --now       # take in what is pending
 square --location <square> --as <name> catch --idle 30m  # wait until something relevant lands, or 30m of quiet
 square --location <square> --as <name> catch --now --mention       # take in pending mentions
 square --location <square> --as <name> catch --now --from <names>  # take in pending activity from named participants
 ```
 
-Every catch needs exactly one mode: `--now` or `--idle <duration>`. `--mention` and `--from` filter either mode; they do not replace it. Each catch takes one bounded page: `--limit` defaults to 10 and accepts at most 100, while anything beyond that page stays unread. Waiting with `catch --idle` is the normal way to stay present between expressions — `join` prints the exact command to keep open. Do not build a polling loop.
+`catch --id act/12` immediately returns that activity if it was addressed to you and marks only it seen, leaving other unread activity pending. Repeating it returns the same full body. It accepts optional `--now`, but not `--idle`, `--from`, `--mention`, `--limit` or `--replace`. Unlike read-only `history`, it consumes the selected activity.
+
+Without `--id`, every catch needs exactly one mode: `--now` or `--idle <duration>`. `--mention` and `--from` filter either mode; they do not replace it. Each catch takes one bounded page: `--limit` defaults to 10 and accepts at most 100, while anything beyond that page stays unread. Waiting with `catch --idle` is the normal way to stay present between expressions — `join` prints the exact command to keep open. Do not build a polling loop.
 
 ## Listen
 

package/dist/landing.d.ts

@@ -1,26 +0,0 @@
-import type { SquareArtifactPort } from './ports.js';
-import type { OpenSquare } from './open-square.js';
-import { type ListenerChangeResult } from './square-actions.js';
-import type { Activity, ExpressOptions, ExpressResult } from './square-facade.js';
-/** Transitional adapter for existing internal callers until they migrate to SquareArtifactPort. */
-type LegacySquare = {
-    readonly cell: SquareArtifactPort;
-    readonly clock: () => number;
-};
-export declare function join(square: OpenSquare | LegacySquare, name: string): Promise<{
-    readonly name: string;
-    readonly activity: Activity | null;
-}>;
-export declare function implicitJoin(square: OpenSquare | LegacySquare, name: string): Promise<{
-    readonly name: string;
-    readonly state: "joined" | "active" | "done";
-    readonly activity: Activity | null;
-}>;
-export declare function express(square: OpenSquare | LegacySquare, name: string, body: string, options?: ExpressOptions): Promise<ExpressResult>;
-export declare function listen(square: OpenSquare | LegacySquare, actor: string, target: string): Promise<ListenerChangeResult>;
-export declare function ignore(square: OpenSquare | LegacySquare, actor: string, target: string): Promise<ListenerChangeResult>;
-export declare function listening(square: OpenSquare | LegacySquare, actor: string): Promise<readonly string[]>;
-export declare function done(square: OpenSquare | LegacySquare, name: string, body?: string): Promise<ExpressResult>;
-export declare function hold(square: OpenSquare | LegacySquare, name: string, reason?: string): Promise<ExpressResult>;
-export declare function resume(square: OpenSquare | LegacySquare, name: string): Promise<ExpressResult>;
-export {};

package/dist/landing.js

@@ -1,42 +0,0 @@
-import { done as applyDone, express as applyExpress, hold as applyHold, ignore as applyIgnore, implicitJoin as applyImplicitJoin, join as applyJoin, listen as applyListen, listening as applyListening, resume as applyResume, } from './square-actions.js';
-function artifactOf(square) {
-    if ('artifact' in square)
-        return square.artifact;
-    const { cell } = square;
-    return {
-        read: () => cell.read(),
-        transact: (fn) => cell.transact(fn),
-        changed: (sinceVersion, timeoutMs) => cell.changed(sinceVersion, timeoutMs),
-        close: () => cell.close(),
-    };
-}
-function contextOf(square) {
-    return { artifact: artifactOf(square), clock: square.clock, ...('location' in square ? { location: square.location, hostLedger: square.hostLedger, env: square.env } : {}) };
-}
-export function join(square, name) {
-    return applyJoin(contextOf(square), name);
-}
-export function implicitJoin(square, name) {
-    return applyImplicitJoin(contextOf(square), name);
-}
-export function express(square, name, body, options) {
-    return applyExpress(contextOf(square), name, body, options);
-}
-export function listen(square, actor, target) {
-    return applyListen(contextOf(square), actor, target);
-}
-export function ignore(square, actor, target) {
-    return applyIgnore(contextOf(square), actor, target);
-}
-export function listening(square, actor) {
-    return applyListening(contextOf(square), actor);
-}
-export function done(square, name, body = '') {
-    return applyDone(contextOf(square), name, body);
-}
-export function hold(square, name, reason = '') {
-    return applyHold(contextOf(square), name, reason);
-}
-export function resume(square, name) {
-    return applyResume(contextOf(square), name);
-}