@astrosheep/square 0.3.45 → 0.3.47

package/dist/square-state.js

@@ -0,0 +1,141 @@
+import fs from 'node:fs';
+import { isWakeRouteKind, SquareError, } from './model.js';
+import { parseActivityId } from './square-core.js';
+const guideNames = ['participant', 'architect', 'brainstorm'];
+const guideContents = new Map(await Promise.all(guideNames.map(async (name) => [name, (await fs.promises.readFile(new URL(`../guides/${name}.md`, import.meta.url), 'utf8')).trim()])));
+function invalidArtifact(detail) {
+    return new SquareError('invalid_args', `Invalid square artifact: ${detail}`);
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, required, optional = []) {
+    const allowed = new Set([...required, ...optional]);
+    return required.every((key) => Object.hasOwn(value, key)) && Object.keys(value).every((key) => allowed.has(key));
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isNonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function isNonblankString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function validateObservation(value) {
+    return isObject(value) && hasExactKeys(value, ['state', 'at']) && value.state === 'seen' && isFiniteNumber(value.at);
+}
+function validateWatchLease(value) {
+    if (!isObject(value) || !hasExactKeys(value, ['leaseId', 'heartbeatAt', 'expiresAt'], ['filter'])
+        || !isNonblankString(value.leaseId) || !isFiniteNumber(value.heartbeatAt)
+        || !isFiniteNumber(value.expiresAt) || value.expiresAt < value.heartbeatAt)
+        return false;
+    if (value.filter === undefined)
+        return true;
+    return isObject(value.filter) && hasExactKeys(value.filter, [], ['participants', 'mention'])
+        && (value.filter.participants === undefined || isStringArray(value.filter.participants))
+        && (value.filter.mention === undefined || typeof value.filter.mention === 'string');
+}
+function validateRecord(value, item) {
+    return isObject(value) && Object.entries(value).every(([key, candidate]) => key.length > 0 && item(candidate));
+}
+function validateRuntime(value) {
+    return isObject(value) && hasExactKeys(value, ['nextActIndex', 'observations', 'leases'])
+        && isNonNegativeInteger(value.nextActIndex)
+        && validateRecord(value.observations, (candidate) => isObject(candidate)
+            && Object.entries(candidate).every(([id, observation]) => parseActivityId(id) !== undefined && validateObservation(observation)))
+        && validateRecord(value.leases, validateWatchLease);
+}
+function validateAssignedRuntimeReferences(runtime) {
+    for (const observations of Object.values(runtime.observations)) {
+        for (const id of Object.keys(observations)) {
+            const index = parseActivityId(id);
+            if (index === undefined)
+                return 'malformed';
+            if (index >= runtime.nextActIndex)
+                return 'future';
+        }
+    }
+    return 'ok';
+}
+function validateActor(value, required) {
+    return required ? isNonblankString(value) : value === undefined || isNonblankString(value);
+}
+function validateStoredAct(value) {
+    if (!isObject(value) || typeof value.kind !== 'string' || !isNonNegativeInteger(value.index) || !isFiniteNumber(value.at))
+        return false;
+    switch (value.kind) {
+        case 'join': return hasExactKeys(value, ['kind', 'actor', 'at', 'index']) && validateActor(value.actor, true);
+        case 'done': return hasExactKeys(value, ['kind', 'actor', 'at', 'index'], ['body']) && validateActor(value.actor, true) && (value.body === undefined || typeof value.body === 'string');
+        case 'say': return hasExactKeys(value, ['kind', 'actor', 'at', 'body', 'index'], ['mentions', 'reach', 'reply'])
+            && validateActor(value.actor, true) && typeof value.body === 'string'
+            && (value.mentions === undefined || isStringArray(value.mentions)) && (value.reach === undefined || value.reach === 'bell')
+            && (value.reply === undefined || isNonNegativeInteger(value.reply));
+        case 'hold': return hasExactKeys(value, ['kind', 'at', 'index'], ['actor', 'body']) && validateActor(value.actor, false) && (value.body === undefined || typeof value.body === 'string');
+        case 'resume': return hasExactKeys(value, ['kind', 'at', 'index'], ['actor']) && validateActor(value.actor, false);
+        case 'read': return hasExactKeys(value, ['kind', 'actor', 'at', 'through', 'index']) && validateActor(value.actor, true) && isNonNegativeInteger(value.through);
+        case 'listen':
+        case 'ignore': return hasExactKeys(value, ['kind', 'actor', 'target', 'at', 'index']) && validateActor(value.actor, true) && validateActor(value.target, true);
+        default: return false;
+    }
+}
+function validateActs(value) {
+    if (!Array.isArray(value) || !value.every(validateStoredAct))
+        return false;
+    let previous = -1;
+    for (const act of value) {
+        if (act.index <= previous || (act.kind === 'say' && act.reply !== undefined && act.reply >= act.index))
+            return false;
+        previous = act.index;
+    }
+    return true;
+}
+export function validateSquareState(value) {
+    if (!isObject(value) || !hasExactKeys(value, ['hardCap', 'preamble', 'warmup', 'acts', 'runtime'], ['throttlePerMinute', 'routes'])
+        || !(value.hardCap === null || (Number.isSafeInteger(value.hardCap) && value.hardCap > 0))
+        || (value.throttlePerMinute !== undefined && (!Number.isSafeInteger(value.throttlePerMinute) || value.throttlePerMinute <= 0))
+        || !isStringArray(value.preamble) || !isStringArray(value.warmup) || !validateActs(value.acts)
+        || (value.routes !== undefined && (!Array.isArray(value.routes) || !value.routes.every((route) => isObject(route) && isWakeRouteKind(route.kind)
+            && typeof route.location === 'string' && typeof route.participant === 'string' && typeof route.sessionId === 'string'
+            && typeof route.channel === 'string' && isObject(route.address) && Object.values(route.address).every((item) => typeof item === 'string')
+            && typeof route.updatedAt === 'number')))
+        || !validateRuntime(value.runtime))
+        throw invalidArtifact('snapshot schema is malformed.');
+    const historyBoundary = value.acts.at(-1)?.index ?? -1;
+    if (value.runtime.nextActIndex <= historyBoundary)
+        throw invalidArtifact('nextActIndex is behind the activity history.');
+    const references = validateAssignedRuntimeReferences(value.runtime);
+    if (references === 'malformed')
+        throw invalidArtifact('snapshot schema is malformed.');
+    if (references === 'future')
+        throw invalidArtifact('runtime references an unassigned activity index.');
+    return value;
+}
+export function emptyRuntimeState(nextActIndex = 0) {
+    return { nextActIndex, observations: {}, leases: {} };
+}
+function normalizedLines(value) {
+    const normalized = value.replace(/\r\n/g, '\n').trim();
+    return normalized === '' ? [] : normalized.split('\n');
+}
+function readGuide(name) {
+    const guide = guideContents.get(name);
+    if (guide === undefined)
+        throw new SquareError('invalid_args', `Unknown square guide: ${name}`);
+    return guide;
+}
+export function createSquareState(options, snippet) {
+    const guides = [readGuide('participant')];
+    if (options.template !== undefined)
+        guides.push(readGuide(options.template));
+    return {
+        hardCap: options.hardCap,
+        ...(options.throttlePerMinute === undefined ? {} : { throttlePerMinute: options.throttlePerMinute }),
+        preamble: normalizedLines(snippet),
+        warmup: normalizedLines(guides.join('\n\n')),
+        acts: [], routes: [], runtime: emptyRuntimeState(),
+    };
+}

package/dist/square-storage.d.ts

@@ -1,20 +1,17 @@
 import { createSquareState, diagnoseSquareFile as diagnoseArtifactFile } from './artifact.js';
+import type { SquareState } from './model.js';
 import type { StateCell } from './state-cell.js';
-import { type SquareState } from './model.js';
-/**
- * The only production module allowed to cross the .square byte boundary.
- * Consumers receive a SquareState and never need to know which codec or lock
- * protects it.
- */
-export { createSquareState, };
+export { createSquareState };
 export declare function readSquareFile(squarePath: string): Promise<SquareState>;
 export declare function probeSquareFile(squarePath: string): Promise<SquareState | undefined>;
 export declare function diagnoseSquareFile(squarePath: string): ReturnType<typeof diagnoseArtifactFile>;
+/** Test-helper snapshot replacement backed by one SQLite artifact. */
 export declare function writeSquareSnapshot(squarePath: string, squareState: SquareState): Promise<void>;
-export declare function withSquareFileLock<T>(squarePath: string, fn: () => T | Promise<T>): Promise<T>;
+/** Race-safe non-force creation for the file adapter. */
+export declare function createSquareSnapshot(squarePath: string, squareState: SquareState): Promise<boolean>;
 /** In-process cell for fast behavior tests and embedded consumers. */
 export declare function createMemoryCell(initial: SquareState): StateCell;
-/** File-backed cell retaining the existing .square codec and lock boundary. */
+/** SQLite-backed cell. Revisions are read from the authoritative database, not file metadata. */
 export declare function createFileCell(squarePath: string): StateCell;
-/** Consumer-facing file cell factory; keeps storage choice behind this module. */
+/** Consumer-facing file cell factory; keeps SQLite framing behind this module. */
 export declare function openSquareCell(squarePath: string): StateCell;

package/dist/square-storage.js

@@ -1,15 +1,9 @@
-import { setTimeout as sleep } from 'node:timers/promises';
 import fs from 'node:fs';
 import path from 'node:path';
-import { createSquareState, diagnoseSquareFile as diagnoseArtifactFile, loadSquare, probeSquare, writeSquareFile, } from './artifact.js';
-import { withFileLock } from './file-lock.js';
-import { LOCK_RETRY_MS } from './runtime.js';
-/**
- * The only production module allowed to cross the .square byte boundary.
- * Consumers receive a SquareState and never need to know which codec or lock
- * protects it.
- */
-export { createSquareState, };
+import { setTimeout as sleep } from 'node:timers/promises';
+import { isDeepStrictEqual } from 'node:util';
+import { createSquareFile, createSquareState, diagnoseSquareFile as diagnoseArtifactFile, loadSquare, probeSquare, readSquareSnapshot, transactSquareSnapshot, writeSquareFile, } from './artifact.js';
+export { createSquareState };
 async function canonicalPath(squarePath) {
     const absolute = path.resolve(squarePath);
     try {
@@ -22,49 +16,24 @@ async function canonicalPath(squarePath) {
         return path.join(parent, path.basename(absolute));
     }
 }
-async function squareFileExists(squarePath) {
-    try {
-        await fs.promises.access(squarePath);
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return false;
-        throw error;
-    }
-}
-async function withSquareFileReadLock(squarePath, fn) {
-    if (!await squareFileExists(squarePath))
-        return fn();
-    try {
-        return await withFileLock(`${squarePath}.lock`, { retryMs: LOCK_RETRY_MS, createParent: false }, fn);
-    }
-    catch (error) {
-        if (!await squareFileExists(squarePath))
-            return fn();
-        throw error;
-    }
-}
 export async function readSquareFile(squarePath) {
-    const canonical = await canonicalPath(squarePath);
-    return withSquareFileReadLock(canonical, () => loadSquare(canonical));
+    return loadSquare(await canonicalPath(squarePath));
 }
 export async function probeSquareFile(squarePath) {
     if (!squarePath.endsWith('.square'))
         return undefined;
-    const canonical = await canonicalPath(squarePath);
-    return withSquareFileReadLock(canonical, () => probeSquare(canonical));
+    return probeSquare(await canonicalPath(squarePath));
 }
 export async function diagnoseSquareFile(squarePath) {
-    const canonical = await canonicalPath(squarePath);
-    return withSquareFileReadLock(canonical, () => diagnoseArtifactFile(canonical));
+    return diagnoseArtifactFile(await canonicalPath(squarePath));
 }
+/** Test-helper snapshot replacement backed by one SQLite artifact. */
 export async function writeSquareSnapshot(squarePath, squareState) {
     await writeSquareFile(await canonicalPath(squarePath), squareState);
 }
-export async function withSquareFileLock(squarePath, fn) {
-    const canonical = await canonicalPath(squarePath);
-    return withFileLock(`${canonical}.lock`, { retryMs: LOCK_RETRY_MS }, fn);
+/** Race-safe non-force creation for the file adapter. */
+export async function createSquareSnapshot(squarePath, squareState) {
+    return createSquareFile(await canonicalPath(squarePath), squareState);
 }
 function cloneState(squareState) {
     return structuredClone(squareState);
@@ -73,6 +42,16 @@ function assertCellOpen(closed) {
     if (closed)
         throw new Error('StateCell is closed');
 }
+function isThenable(value) {
+    return (typeof value === 'object' || typeof value === 'function') && value !== null
+        && typeof value.then === 'function';
+}
+function discardThenable(value) {
+    void Promise.resolve(value).catch(() => undefined);
+}
+function isBusy(error) {
+    return error instanceof Error && /database is locked|database is busy|SQLITE_BUSY/i.test(error.message);
+}
 /** In-process cell for fast behavior tests and embedded consumers. */
 export function createMemoryCell(initial) {
     let state = cloneState(initial);
@@ -89,15 +68,21 @@ export function createMemoryCell(initial) {
             waiter.resolve(true);
         }
     }
-    const cell = {
+    return {
         transact(fn) {
             assertCellOpen(closed);
-            let operation;
-            operation = tail.then(() => {
+            const operation = tail.then(() => {
                 assertCellOpen(closed);
-                const working = cloneState(state);
-                const outcome = fn(working, version);
-                if (outcome.state !== undefined) {
+                const current = cloneState(state);
+                const outcome = fn(current, version);
+                if (isThenable(outcome)) {
+                    discardThenable(outcome);
+                    throw new TypeError('Square artifact transitions must be synchronous.');
+                }
+                if (typeof outcome !== 'object' || outcome === null || !Object.hasOwn(outcome, 'result')) {
+                    throw new TypeError('Square artifact transition must return { state?, result }.');
+                }
+                if (outcome.state !== undefined && !isDeepStrictEqual(outcome.state, state)) {
                     state = cloneState(outcome.state);
                     version += 1;
                     publish();
@@ -110,6 +95,7 @@ export function createMemoryCell(initial) {
         async read() {
             assertCellOpen(closed);
             await tail;
+            assertCellOpen(closed);
             return { state: cloneState(state), version };
         },
         changed(sinceVersion, timeoutMs) {
@@ -122,10 +108,7 @@ export function createMemoryCell(initial) {
                 const waiter = {
                     since: sinceVersion,
                     resolve,
-                    timer: setTimeout(() => {
-                        waiters.delete(waiter);
-                        resolve(false);
-                    }, timeoutMs),
+                    timer: setTimeout(() => { waiters.delete(waiter); resolve(false); }, timeoutMs),
                 };
                 waiters.add(waiter);
             });
@@ -142,93 +125,79 @@ export function createMemoryCell(initial) {
             }
         },
     };
-    return cell;
-}
-async function fileFingerprint(squarePath) {
-    try {
-        const stat = await fs.promises.stat(squarePath);
-        return `${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
-    }
-    catch {
-        return 'missing';
-    }
 }
-/** File-backed cell retaining the existing .square codec and lock boundary. */
+/** SQLite-backed cell. Revisions are read from the authoritative database, not file metadata. */
 export function createFileCell(squarePath) {
     let closed = false;
-    let version = 0;
-    let fingerprint;
-    let cached;
-    let canonicalSquarePath;
-    async function storagePath() {
-        canonicalSquarePath ??= await canonicalPath(squarePath);
-        return canonicalSquarePath;
-    }
-    async function observe() {
-        const next = await fileFingerprint(await storagePath());
-        if (fingerprint === undefined) {
-            fingerprint = next;
-        }
-        else if (next !== fingerprint) {
-            fingerprint = next;
-            cached = undefined;
-            version += 1;
-        }
-        return fingerprint;
+    let storage;
+    let tail = Promise.resolve();
+    const cancel = new AbortController();
+    function storagePath() {
+        storage ??= canonicalPath(squarePath);
+        return storage;
     }
-    async function currentStateUnderLock() {
-        const observed = await observe();
-        if (cached?.fingerprint === observed)
-            return cloneState(cached.state);
-        const decoded = await loadSquare(await storagePath());
-        cached = { fingerprint: observed, state: cloneState(decoded) };
-        return cloneState(cached.state);
+    function abortError() {
+        return new Error('StateCell is closed');
     }
     return {
-        async transact(fn) {
+        transact(fn) {
             assertCellOpen(closed);
-            const canonical = await storagePath();
-            return withFileLock(`${canonical}.lock`, { retryMs: LOCK_RETRY_MS }, async () => {
+            const operation = tail.then(async () => {
                 assertCellOpen(closed);
-                const current = await currentStateUnderLock();
-                const working = cloneState(current);
-                const outcome = fn(working, version);
-                if (outcome.state !== undefined) {
-                    await writeSquareFile(canonical, outcome.state);
-                    fingerprint = await fileFingerprint(canonical);
-                    cached = { fingerprint, state: cloneState(outcome.state) };
-                    version += 1;
-                }
-                return outcome.result;
+                const result = await transactSquareSnapshot(await storagePath(), fn, cancel.signal);
+                return result.result;
             });
+            tail = operation.then(() => undefined, () => undefined);
+            return operation;
         },
         async read() {
             assertCellOpen(closed);
-            return withSquareFileReadLock(await storagePath(), async () => {
-                assertCellOpen(closed);
-                return { state: await currentStateUnderLock(), version };
-            });
+            await tail;
+            assertCellOpen(closed);
+            const snapshot = await readSquareSnapshot(await storagePath(), cancel.signal);
+            return { state: cloneState(snapshot.state), version: snapshot.revision };
         },
         async changed(sinceVersion, timeoutMs) {
             assertCellOpen(closed);
             const deadline = Date.now() + Math.max(0, timeoutMs);
-            while (true) {
-                await observe();
-                if (version > sinceVersion)
-                    return true;
+            while (!closed) {
                 const remaining = deadline - Date.now();
-                if (remaining <= 0)
+                const timeout = AbortSignal.timeout(Math.max(1, remaining));
+                const readSignal = AbortSignal.any([cancel.signal, timeout]);
+                try {
+                    if ((await readSquareSnapshot(await storagePath(), readSignal)).revision > sinceVersion)
+                        return true;
+                }
+                catch (error) {
+                    if (closed || cancel.signal.aborted || timeout.aborted)
+                        return false;
+                    if (!isBusy(error))
+                        throw error;
+                }
+                const nextRemaining = deadline - Date.now();
+                if (nextRemaining <= 0)
                     return false;
-                await sleep(Math.min(25, remaining));
-                assertCellOpen(closed);
+                try {
+                    await sleep(Math.min(25, nextRemaining), undefined, { signal: cancel.signal });
+                }
+                catch (error) {
+                    if (closed || cancel.signal.aborted)
+                        return false;
+                    throw error;
+                }
             }
+            return false;
         },
         async close() {
+            if (closed)
+                return;
             closed = true;
+            cancel.abort(abortError());
+            await tail;
         },
     };
 }
-/** Consumer-facing file cell factory; keeps storage choice behind this module. */
+/** Consumer-facing file cell factory; keeps SQLite framing behind this module. */
 export function openSquareCell(squarePath) {
     return createFileCell(squarePath);
 }

package/dist/state-cell.d.ts

@@ -4,10 +4,7 @@ export interface StateCell {
     transact<R>(fn: (state: SquareState, version: number) => {
         state?: SquareState;
         result: R;
-    } | Promise<{
-        state?: SquareState;
-        result: R;
-    }>): Promise<R>;
+    }): Promise<R>;
     read(): Promise<{
         state: SquareState;
         version: number;

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/guides/participant-ownership.md

@@ -110,7 +110,7 @@ row.
 1. Resolve the requested name and collect the currently active bindings for
    that name. The current session is excluded from the old-owner set only when
    it is already the owner and this is a reconnect, not a kick.
-2. Under the artifact lock, commit two lifecycle activities as one transaction:
+2. In one artifact transaction, commit two lifecycle activities:
    `done` for the standing participant, followed immediately by `join` for the
    reclaimed name. If this transaction cannot commit, nothing is kicked.
 3. In the same artifact transaction, remove every route for the kicked
@@ -152,8 +152,8 @@ owner. It must not append a second `done` for the new owner.
 ## Concurrency and Recovery
 
 The artifact transaction serializes participant lifecycle activities. The host
-ledger lock serializes binding rows. These locks protect different facts and
-must not be replaced with a copied sidecar or a display-level mutex.
+ledger lock serializes binding rows. They protect different facts and must not
+be replaced with a copied sidecar or a display-level mutex.
 
 The safe ordering is:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.45",
+  "version": "0.3.47",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
   "author": "astrosheep",
   "license": "MIT",
   "engines": {
-    "node": ">=22.5.0"
+    "node": "^22.16.0 || >=24.0.0"
   },
   "devDependencies": {
     "@getpaseo/client": "^0.3.1",

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 {};