@astrosheep/square 0.3.46 → 0.3.48

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

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.46",
+  "version": "0.3.48",
   "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.48",
   "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/boundary-presentation.js

@@ -30,6 +30,9 @@ export function pendingAtBoundary(inbox) {
 export function renderPendingAtBoundary(inbox) {
     return renderBoundary(inbox).context;
 }
+function frameBoundary(lines) {
+    return `\n${lines.join('\n')}\n`;
+}
 function renderBoundary(inbox) {
     const count = pendingCount(inbox);
     const noun = count === 1 ? 'notification' : 'notifications';
@@ -52,7 +55,7 @@ function renderBoundary(inbox) {
             }),
         ].join('\n');
         const omittedAfter = omitted + queued.length - index - 1;
-        const prospective = [
+        const prospective = frameBoundary([
             header,
             ...blocks,
             block,
@@ -60,7 +63,7 @@ function renderBoundary(inbox) {
                 ? [`… ${omittedAfter} ${omittedAfter === 1 ? 'notification' : 'notifications'} omitted.`]
                 : []),
             ...footer,
-        ].join('\n');
+        ]);
         if (prospective.length > CONTEXT_MAX) {
             omitted += 1;
             continue;
@@ -73,14 +76,14 @@ function renderBoundary(inbox) {
         });
     }
     return {
-        context: [
+        context: frameBoundary([
             header,
             ...blocks,
             ...(omitted > 0
                 ? [`… ${omitted} ${omitted === 1 ? 'notification' : 'notifications'} omitted.`]
                 : []),
             ...footer,
-        ].join('\n'),
+        ]),
         complete,
     };
 }

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

@@ -4,18 +4,17 @@ import { waitForSessionPending } from '../dist/inbox.js';
 import { projectSessionBindings } from '../dist/square-projections.js';
 import { createHostLedgerPort } from '../dist/host-ledger-file-adapter.js';
 
-const PI_SEND_TIMEOUT_MS = 5_000;
-const DEFAULT_PI_BOUNDARY_TIMEOUT_MS = 2_000;
+class PiDeliveryDroppedError extends Error {
+  constructor() {
+    super('Pi discarded the queued Square notification');
+    this.name = 'PiDeliveryDroppedError';
+  }
+}
 
 function sessionBindings(sessionId) {
   return projectSessionBindings({ hostLedger: createHostLedgerPort(), sessionId });
 }
 
-function piBoundaryTimeoutMs() {
-  const configured = Number.parseInt(process.env.SQUARE_PI_BOUNDARY_TIMEOUT_MS || '', 10);
-  return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_PI_BOUNDARY_TIMEOUT_MS;
-}
-
 export function pendingInbox(inbox) {
   return inbox.filter((item) => item.notifications?.length > 0);
 }
@@ -33,41 +32,82 @@ export function renderPiInbox(inbox) {
 export default function squarePiExtension(pi) {
   let sessionId;
   let sessionCwd;
-  let joiningContext;
   let previousSessionId;
   let watcher;
   let watcherAbort;
   let generation = 0;
-  let presenting = false;
-  let settledSerial = 0;
-  let settledWaiters = [];
   const handledPending = new Set();
+  const landingAcks = new Map();
   let retryAfterChange = false;
   let retryWait;
-  const present = (deliver, signal) => sessionId === undefined ? undefined : presentPendingAtBoundary(sessionId, deliver, undefined, undefined, signal);
+  let turnIndex = 0;
+  let activeTurn;
+  let currentRunSignal;
+  const deferredSteers = new Set();
 
-  const presentAtBoundary = (deliver) => {
-    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) {
-      clearTimeout(timer);
-      return undefined;
-    }
-    return pending.finally(() => clearTimeout(timer));
+  const waitForAgentSettled = (signal) => new Promise((resolve, reject) => {
+    const deferred = {
+      release() {
+        deferredSteers.delete(deferred);
+        signal.removeEventListener('abort', abort);
+        resolve();
+      },
+    };
+    const abort = () => {
+      deferredSteers.delete(deferred);
+      signal.removeEventListener('abort', abort);
+      reject(signal.reason || new Error('Pi native injection aborted'));
+    };
+    deferredSteers.add(deferred);
+    if (signal.aborted) abort();
+    else signal.addEventListener('abort', abort, { once: true });
+  });
+
+  const releaseDeferredSteers = () => {
+    for (const deferred of [...deferredSteers]) deferred.release();
   };
 
-  const waitForSettled = (serial, signal) => {
-    if (settledSerial !== serial) return Promise.resolve();
-    return new Promise((resolve) => {
-      const waiter = { serial, resolve };
-      settledWaiters.push(waiter);
-      if (signal) signal.addEventListener('abort', () => {
-        const index = settledWaiters.indexOf(waiter);
-        if (index >= 0) settledWaiters.splice(index, 1);
-        resolve();
-      }, { once: true });
+  const failAcks = (error) => {
+    const acks = [...landingAcks.values()].flatMap((waiters) => [...waiters]);
+    for (const ack of acks) ack.settle(error);
+  };
+
+  const acknowledgeLanding = (message) => {
+    if (message?.role !== 'custom' || message.customType !== 'square' || typeof message.content !== 'string') return;
+    const acks = landingAcks.get(message.content);
+    if (acks === undefined) return;
+    for (const ack of [...acks]) ack.settle();
+  };
+
+  const waitForLanding = (content, signal, kind) => {
+    let ack;
+    const promise = new Promise((resolve, reject) => {
+      const abort = () => ack.settle(signal.reason || new Error('Pi native injection aborted'));
+      ack = {
+        kind,
+        sentAfterTurn: turnIndex,
+        emptyTurnWindows: 0,
+        dropAfterSettled: false,
+        settle(error) {
+          if (ack.settled) return;
+          ack.settled = true;
+          signal.removeEventListener('abort', abort);
+          const acks = landingAcks.get(content);
+          if (acks?.delete(ack) && acks.size === 0) landingAcks.delete(content);
+          if (error === undefined) resolve();
+          else reject(error);
+        },
+      };
+      let acks = landingAcks.get(content);
+      if (acks === undefined) {
+        acks = new Set();
+        landingAcks.set(content, acks);
+      }
+      acks.add(ack);
+      if (signal.aborted) abort();
+      else signal.addEventListener('abort', abort, { once: true });
     });
+    return { promise, ack };
   };
 
   // A transport may keep its promise pending while Pi is shutting down or
@@ -88,7 +128,7 @@ export default function squarePiExtension(pi) {
     signal.addEventListener('abort', finish, { once: true });
   });
 
-  const wake = async (piContext, token, signal) => {
+  const wake = async (token, signal) => {
     const armDeferredRetry = () => {
       const controller = new AbortController();
       let resolveArmed;
@@ -108,14 +148,26 @@ export default function squarePiExtension(pi) {
     };
 
     while (sessionId !== undefined && token === generation && !signal.aborted) {
-      if ((await sessionBindings(sessionId)).length === 0) {
+      try {
+        if ((await sessionBindings(sessionId)).length === 0) {
+          await pause(signal, 1_000);
+          continue;
+        }
+      } catch {
         await pause(signal, 1_000);
         continue;
       }
+
       const deferredRetry = retryAfterChange;
-      const pending = deferredRetry && retryWait !== undefined
-        ? await retryWait
-        : await waitForSessionPending(sessionId, 30_000, { signal, excludeKeys: handledPending });
+      let pending;
+      try {
+        pending = deferredRetry && retryWait !== undefined
+          ? await retryWait
+          : await waitForSessionPending(sessionId, 30_000, { signal, excludeKeys: handledPending });
+      } catch {
+        await pause(signal, 1_000);
+        continue;
+      }
       if (sessionId === undefined || token !== generation || signal.aborted) return;
       if (pending.length === 0) {
         if (deferredRetry) {
@@ -126,112 +178,136 @@ export default function squarePiExtension(pi) {
       }
       retryAfterChange = false;
       retryWait = undefined;
-      if (!piContext.isIdle()) {
-        const serial = settledSerial;
-        await waitForSettled(serial, signal);
-        continue;
-      }
-      if (presenting) continue;
+
       const keys = inboxKeys(pending);
-      presenting = true;
       const deferred = armDeferredRetry();
       const retryArmed = await deferred.armed;
       if (!retryArmed) {
         deferred.cancel();
-        presenting = false;
         continue;
       }
       let keepDeferred = false;
       try {
-        const delivered = await presentPendingAtBoundary(
+        await presentPendingAtBoundary(
           sessionId,
           async (content) => {
-            const send = Promise.resolve(pi.sendMessage(
-              { customType: 'square', content, display: true },
-              { deliverAs: 'steer', triggerTurn: true },
-            ));
-            let timer;
+            if (currentRunSignal?.aborted) await waitForAgentSettled(signal);
+            const landing = waitForLanding(content, signal, 'steer');
             try {
-              await Promise.race([
-                send,
-                new Promise((_, reject) => {
-                  if (signal.aborted) {
-                    reject(signal.reason || new Error('Pi native injection aborted'));
-                    return;
-                  }
-                  signal.addEventListener('abort', () => reject(signal.reason || new Error('Pi native injection aborted')), { once: true });
-                }),
-                new Promise((_, reject) => {
-                  timer = setTimeout(() => reject(new Error('Pi native injection timed out')), PI_SEND_TIMEOUT_MS);
-                }),
-              ]);
-            } finally {
-              if (timer !== undefined) clearTimeout(timer);
+              Promise.resolve(pi.sendMessage(
+                { customType: 'square', content, display: true },
+                { deliverAs: 'steer', triggerTurn: true },
+              )).catch((error) => landing.ack.settle(error));
+            } catch (error) {
+              landing.ack.settle(error);
             }
-            return true;
+            return landing.promise;
           },
           undefined,
           undefined,
           signal,
         );
-        if (delivered === true || delivered === undefined) {
-          for (const key of keys) handledPending.add(key);
+        for (const key of keys) handledPending.add(key);
+      } catch (error) {
+        if (error instanceof PiDeliveryDroppedError) {
+          deferred.cancel();
+          continue;
         }
-      } catch {
         // The next state edge is already being observed before native injection starts.
         retryAfterChange = true;
         retryWait = deferred.pending;
         keepDeferred = true;
       } finally {
         if (!keepDeferred) deferred.cancel();
-        presenting = false;
       }
     }
   };
 
   pi.on('session_start', async (_event, ctx) => {
     generation += 1;
+    failAcks(new Error('Pi session replaced'));
     stopWatcher();
     handledPending.clear();
     retryAfterChange = false;
     retryWait = undefined;
+    turnIndex = 0;
+    activeTurn = undefined;
+    currentRunSignal = undefined;
     sessionId = ctx.sessionManager.getSessionId();
     sessionCwd = ctx.cwd || process.cwd();
     previousSessionId = process.env.SQUARE_PI_SESSION_ID;
     process.env.SQUARE_PI_SESSION_ID = sessionId;
-    joiningContext = undefined;
-    void automaticSessionStart('pi', sessionId, sessionCwd).catch(() => undefined);
-    watcherAbort = new AbortController();
     const token = generation;
-    watcher = wake(ctx, token, watcherAbort.signal).catch(() => undefined);
+    watcherAbort = new AbortController();
+    const signal = watcherAbort.signal;
+    void automaticSessionStart('pi', sessionId, sessionCwd).then((context) => {
+      if (context === undefined || sessionId === undefined || token !== generation) return;
+      const landing = waitForLanding(context, signal, 'nextTurn');
+      try {
+        Promise.resolve(pi.sendMessage(
+          { customType: 'square', content: context, display: true },
+          { deliverAs: 'nextTurn' },
+        )).catch((error) => landing.ack.settle(error));
+      } catch {
+        // Joining context is advisory; an unavailable Pi transport does not block startup.
+        landing.ack.settle(new Error('Pi joining-context injection failed'));
+      }
+      void landing.promise.catch(() => undefined);
+    }).catch(() => undefined);
+    watcher = wake(token, signal).catch(() => undefined);
   });
 
-  pi.on('agent_settled', async () => {
-    settledSerial += 1;
-    const waiters = settledWaiters;
-    settledWaiters = [];
-    for (const waiter of waiters) waiter.resolve();
+  pi.on('agent_start', async (_event, ctx) => {
+    currentRunSignal = ctx?.getSignal?.();
   });
 
-  pi.on('before_agent_start', async () => {
-    try {
-      if (joiningContext) {
-        const context = joiningContext;
-        joiningContext = undefined;
-        return { message: { customType: 'square', content: context, display: true } };
+  pi.on('message_end', async (event) => {
+    if (activeTurn !== undefined && (event.message?.role === 'user' || event.message?.role === 'custom')) {
+      activeTurn.hasInput = true;
+    }
+    acknowledgeLanding(event.message);
+  });
+
+  pi.on('turn_start', async () => {
+    turnIndex += 1;
+    activeTurn = { index: turnIndex, hasInput: false, signal: currentRunSignal };
+  });
+
+  pi.on('turn_end', async (event, ctx) => {
+    const turn = activeTurn;
+    activeTurn = undefined;
+    const acks = [...landingAcks.values()].flatMap((waiters) => [...waiters]);
+    if (event.message?.stopReason === 'aborted' && ctx?.mode === 'tui' && turn?.signal !== undefined) {
+      for (const ack of acks) {
+        if (ack.kind === 'steer') ack.dropAfterSettled = true;
       }
-      if (presenting) return undefined;
-      return await presentAtBoundary((context) => ({ message: { customType: 'square', content: context, display: true } }));
-    } catch {
-      return undefined;
+      return;
+    }
+    if (turn === undefined) return;
+    for (const ack of acks) {
+      if (ack.kind !== 'steer' || ack.dropAfterSettled || turn.index <= ack.sentAfterTurn) continue;
+      if (turn.hasInput) {
+        ack.emptyTurnWindows = 0;
+      } else {
+        ack.emptyTurnWindows += 1;
+        if (ack.emptyTurnWindows >= 2) ack.settle(new PiDeliveryDroppedError());
+      }
+    }
+  });
+
+  pi.on('agent_settled', async () => {
+    currentRunSignal = undefined;
+    const acks = [...landingAcks.values()].flatMap((waiters) => [...waiters]);
+    for (const ack of acks) {
+      if (ack.dropAfterSettled) ack.settle(new PiDeliveryDroppedError());
     }
+    releaseDeferredSteers();
   });
 
   pi.on('session_shutdown', async () => {
     generation += 1;
+    failAcks(new Error('Pi session ended'));
     stopWatcher();
-    for (const waiter of settledWaiters) waiter.resolve();
-    settledWaiters = [];
     if (sessionId && sessionCwd) void automaticSessionEnd('pi', sessionId, sessionCwd).catch(() => undefined);
     if (process.env.SQUARE_PI_SESSION_ID === sessionId) {
       if (previousSessionId === undefined) delete process.env.SQUARE_PI_SESSION_ID;
@@ -239,8 +315,8 @@ export default function squarePiExtension(pi) {
     }
     sessionId = undefined;
     sessionCwd = undefined;
-    joiningContext = undefined;
-    presenting = false;
     retryWait = undefined;
+    activeTurn = undefined;
+    currentRunSignal = undefined;
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.46",
+  "version": "0.3.48",
   "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);
-}