@astrosheep/square 0.3.28 → 0.3.30

package/dist/square-storage.js

@@ -10,13 +10,15 @@ import { LOCK_RETRY_MS, LOCK_STALE_MS } from './runtime.js';
  */
 export { createSquareState, };
 export async function readSquareFile(squarePath) {
-    return loadSquare(squarePath);
+    return withSquareFileLock(squarePath, () => loadSquare(squarePath));
 }
 export async function probeSquareFile(squarePath) {
-    return probeSquare(squarePath);
+    if (!squarePath.endsWith('.square'))
+        return undefined;
+    return withSquareFileLock(squarePath, () => probeSquare(squarePath));
 }
 export async function diagnoseSquareFile(squarePath) {
-    return diagnoseArtifactFile(squarePath);
+    return withSquareFileLock(squarePath, () => diagnoseArtifactFile(squarePath));
 }
 export async function writeSquareSnapshot(squarePath, squareState) {
     await writeSquareFile(squarePath, squareState);
@@ -129,11 +131,11 @@ export function createFileCell(squarePath) {
         }
         return fingerprint;
     }
-    async function currentState() {
+    async function currentStateUnderLock() {
         const observed = await observe();
         if (cached?.fingerprint === observed)
             return cloneState(cached.state);
-        const decoded = await readSquareFile(squarePath);
+        const decoded = await loadSquare(squarePath);
         cached = { fingerprint: observed, state: cloneState(decoded) };
         return cloneState(cached.state);
     }
@@ -142,7 +144,7 @@ export function createFileCell(squarePath) {
             assertCellOpen(closed);
             return withFileLock(`${squarePath}.lock`, { retryMs: LOCK_RETRY_MS, staleMs: LOCK_STALE_MS }, async () => {
                 assertCellOpen(closed);
-                const current = await currentState();
+                const current = await currentStateUnderLock();
                 const working = cloneState(current);
                 const outcome = fn(working, version);
                 if (outcome.state !== undefined) {
@@ -156,7 +158,10 @@ export function createFileCell(squarePath) {
         },
         async read() {
             assertCellOpen(closed);
-            return { state: await currentState(), version };
+            return withSquareFileLock(squarePath, async () => {
+                assertCellOpen(closed);
+                return { state: await currentStateUnderLock(), version };
+            });
         },
         async changed(sinceVersion, timeoutMs) {
             assertCellOpen(closed);

package/dist/square-wiring.js

@@ -73,7 +73,7 @@ export class Square {
     snapshot() { return snapshot(this.square); }
     history(query) { return history(this.square, query); }
     async recognize(env) {
-        const registered = localParticipantName(this.square.location, env);
+        const registered = await localParticipantName(this.square.location, env);
         if (registered === undefined)
             return null;
         const canonicalName = await currentParticipant(this.square, registered);

package/dist/wake-attempts.d.ts

@@ -16,24 +16,24 @@ export interface WakeAttempt {
     diagnostic?: unknown;
 }
 export declare function wakeAttemptsPath(env?: NodeJS.ProcessEnv): string;
-export declare function wakeAttentionKey(attention: WakeAttention): string;
+export declare function wakeAttentionKey(attention: WakeAttention): Promise<string>;
 export declare function readWakeAttempts(opts?: {
     attention?: WakeAttention;
     now?: number;
     env?: NodeJS.ProcessEnv;
-}): WakeAttempt[];
+}): Promise<WakeAttempt[]>;
 export declare function terminalWakeEvidence(attempts: readonly WakeAttempt[]): WakeAttempt | undefined;
 export declare function terminalWakeAttempt(attention: WakeAttention, opts?: {
     now?: number;
     env?: NodeJS.ProcessEnv;
-}): WakeAttempt | undefined;
+}): Promise<WakeAttempt | undefined>;
 export declare function isWakeRouteAttemptable(route: Pick<WakeRoute, 'kind' | 'updatedAt'>, attempts: readonly WakeAttempt[]): boolean;
 export declare function hasAttemptableWakeRoute(routes: readonly Pick<WakeRoute, 'kind' | 'updatedAt'>[], attempts: readonly WakeAttempt[]): boolean;
 export declare function nextWakeAttemptNumber(attention: WakeAttention, opts?: {
     now?: number;
     env?: NodeJS.ProcessEnv;
-}): number;
+}): Promise<number>;
 export declare function recordWakeAttempt(attempt: Omit<WakeAttempt, 'at'> & {
     at?: number;
-}, env?: NodeJS.ProcessEnv): WakeAttempt;
-export declare function recordRecoveredUnknown(attention: WakeAttention, lease: Pick<NotifyLease, 'attemptN' | 'routeKind'>, env?: NodeJS.ProcessEnv, at?: number): WakeAttempt | undefined;
+}, env?: NodeJS.ProcessEnv): Promise<WakeAttempt>;
+export declare function recordRecoveredUnknown(attention: WakeAttention, lease: Pick<NotifyLease, 'attemptN' | 'routeKind'>, env?: NodeJS.ProcessEnv, at?: number): Promise<WakeAttempt | undefined>;

package/dist/wake-attempts.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { withFileLockSync } from './file-lock.js';
+import { withFileLock } from './file-lock.js';
 import { isWakeRouteKind, nameKey } from './model.js';
 import { canonicalSquarePath } from './registry.js';
 import { formatActivityId, parseActivityId } from './square-core.js';
@@ -12,8 +12,8 @@ const VALID_OUTCOMES = new Set(['accepted', 'unknown', 'failed']);
 export function wakeAttemptsPath(env = process.env) {
     return env.SQUARE_WAKE_ATTEMPTS || path.join(os.homedir(), '.square', 'wake-attempts.ndjsonl');
 }
-export function wakeAttentionKey(attention) {
-    return JSON.stringify([canonicalSquarePath(attention.squarePath), formatActivityId(attention.actIndex), nameKey(attention.recipient)]);
+export async function wakeAttentionKey(attention) {
+    return JSON.stringify([await canonicalSquarePath(attention.squarePath), formatActivityId(attention.actIndex), nameKey(attention.recipient)]);
 }
 function parseRow(raw, now) {
     let value;
@@ -39,10 +39,10 @@ function parseRow(raw, now) {
         return undefined;
     return row;
 }
-function readRowsFromFile(filePath, now) {
+async function readRowsFromFile(filePath, now) {
     let raw;
     try {
-        raw = fs.readFileSync(filePath, 'utf8');
+        raw = await fs.promises.readFile(filePath, 'utf8');
     }
     catch (error) {
         if (error.code === 'ENOENT')
@@ -51,25 +51,25 @@ function readRowsFromFile(filePath, now) {
     }
     return raw.split('\n').filter(Boolean).map((line) => parseRow(line, now)).filter((row) => row !== undefined);
 }
-function readRows(env, now) {
+async function readRows(env, now) {
     return readRowsFromFile(wakeAttemptsPath(env), now);
 }
-function writeRows(filePath, rows) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+async function writeRows(filePath, rows) {
+    await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
     const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-    fs.writeFileSync(temporary, rows.map((row) => JSON.stringify(row)).join('\n') + (rows.length ? '\n' : ''), {
+    await fs.promises.writeFile(temporary, rows.map((row) => JSON.stringify(row)).join('\n') + (rows.length ? '\n' : ''), {
         mode: 0o600,
     });
-    fs.renameSync(temporary, filePath);
+    await fs.promises.rename(temporary, filePath);
 }
-function fromRow(row) {
+async function fromRow(row) {
     const actIndex = parseActivityId(row.attention.act_id);
     if (actIndex === undefined)
         throw new Error(`Invalid wake activity id: ${row.attention.act_id}`);
     return {
         at: row.ts,
         attention: {
-            squarePath: canonicalSquarePath(row.attention.square_path),
+            squarePath: await canonicalSquarePath(row.attention.square_path),
             actIndex,
             recipient: row.attention.recipient,
         },
@@ -81,18 +81,20 @@ function fromRow(row) {
         ...(row.diagnostic === undefined ? {} : { diagnostic: row.diagnostic }),
     };
 }
-export function readWakeAttempts(opts = {}) {
+export async function readWakeAttempts(opts = {}) {
     const now = opts.now ?? Date.now();
-    const expected = opts.attention === undefined ? undefined : wakeAttentionKey(opts.attention);
-    return readRows(opts.env ?? process.env, now)
-        .map(fromRow)
-        .filter((attempt) => expected === undefined || wakeAttentionKey(attempt.attention) === expected);
+    const expected = opts.attention === undefined ? undefined : await wakeAttentionKey(opts.attention);
+    const attempts = await Promise.all((await readRows(opts.env ?? process.env, now)).map(fromRow));
+    if (expected === undefined)
+        return attempts;
+    const keys = await Promise.all(attempts.map((attempt) => wakeAttentionKey(attempt.attention)));
+    return attempts.filter((_, index) => keys[index] === expected);
 }
 export function terminalWakeEvidence(attempts) {
     return attempts.findLast((attempt) => attempt.outcome === 'accepted' || attempt.outcome === 'unknown');
 }
-export function terminalWakeAttempt(attention, opts = {}) {
-    return terminalWakeEvidence(readWakeAttempts({ attention, ...opts }));
+export async function terminalWakeAttempt(attention, opts = {}) {
+    return terminalWakeEvidence(await readWakeAttempts({ attention, ...opts }));
 }
 export function isWakeRouteAttemptable(route, attempts) {
     if (terminalWakeEvidence(attempts) !== undefined)
@@ -103,8 +105,8 @@ export function isWakeRouteAttemptable(route, attempts) {
 export function hasAttemptableWakeRoute(routes, attempts) {
     return routes.some((route) => isWakeRouteAttemptable(route, attempts));
 }
-export function nextWakeAttemptNumber(attention, opts = {}) {
-    return readWakeAttempts({ attention, ...opts }).reduce((highest, attempt) => Math.max(highest, attempt.attemptN), 0) + 1;
+export async function nextWakeAttemptNumber(attention, opts = {}) {
+    return (await readWakeAttempts({ attention, ...opts })).reduce((highest, attempt) => Math.max(highest, attempt.attemptN), 0) + 1;
 }
 function redact(value, secret) {
     if (typeof value === 'string') {
@@ -118,13 +120,13 @@ function redact(value, secret) {
     }
     return value;
 }
-function toRow(attempt, env) {
+async function toRow(attempt, env) {
     const safe = redact(attempt, env.PASEO_PASSWORD);
     return {
         v: 1,
         ts: safe.at,
         attention: {
-            square_path: canonicalSquarePath(safe.attention.squarePath),
+            square_path: await canonicalSquarePath(safe.attention.squarePath),
             act_id: formatActivityId(safe.attention.actIndex),
             recipient: safe.attention.recipient,
         },
@@ -136,7 +138,7 @@ function toRow(attempt, env) {
         ...(safe.diagnostic === undefined ? {} : { diagnostic: safe.diagnostic }),
     };
 }
-export function recordWakeAttempt(attempt, env = process.env) {
+export async function recordWakeAttempt(attempt, env = process.env) {
     const value = { ...attempt, at: attempt.at ?? Date.now() };
     if (!isWakeRouteKind(value.routeKind))
         throw new Error('Wake attempts require a real adapter route kind.');
@@ -144,19 +146,25 @@ export function recordWakeAttempt(attempt, env = process.env) {
         throw new Error(`${value.outcome} wake attempts require a transport signature.`);
     }
     const file = wakeAttemptsPath(env);
-    withFileLockSync(`${file}.lock`, { retryMs: LOCK_RETRY_MS, staleMs: LOCK_STALE_MS }, () => {
-        writeRows(file, [...readRowsFromFile(file, value.at), toRow(value, env)]);
+    await withFileLock(`${file}.lock`, { retryMs: LOCK_RETRY_MS, staleMs: LOCK_STALE_MS }, async () => {
+        await writeRows(file, [...await readRowsFromFile(file, value.at), await toRow(value, env)]);
     });
     return value;
 }
-export function recordRecoveredUnknown(attention, lease, env = process.env, at = Date.now()) {
+export async function recordRecoveredUnknown(attention, lease, env = process.env, at = Date.now()) {
     const routeKind = lease.routeKind;
     if (lease.attemptN === undefined || !isWakeRouteKind(routeKind))
         return undefined;
     const file = wakeAttemptsPath(env);
-    return withFileLockSync(`${file}.lock`, { retryMs: LOCK_RETRY_MS, staleMs: LOCK_STALE_MS }, () => {
-        const rows = readRowsFromFile(file, at);
-        const attempts = rows.map(fromRow).filter((attempt) => wakeAttentionKey(attempt.attention) === wakeAttentionKey(attention));
+    return withFileLock(`${file}.lock`, { retryMs: LOCK_RETRY_MS, staleMs: LOCK_STALE_MS }, async () => {
+        const rows = await readRowsFromFile(file, at);
+        const expected = await wakeAttentionKey(attention);
+        const attempts = [];
+        for (const row of rows) {
+            const attempt = await fromRow(row);
+            if (await wakeAttentionKey(attempt.attention) === expected)
+                attempts.push(attempt);
+        }
         const terminal = terminalWakeEvidence(attempts);
         if (terminal !== undefined)
             return terminal;
@@ -169,7 +177,7 @@ export function recordRecoveredUnknown(attention, lease, env = process.env, at =
             attemptN: lease.attemptN,
             message: 'The notification worker ended after dispatch began; transport acceptance is unknown.',
         };
-        writeRows(file, [...rows, toRow(value, env)]);
+        await writeRows(file, [...rows, await toRow(value, env)]);
         return value;
     });
 }

package/dist/wake-evidence.d.ts

@@ -15,7 +15,7 @@ export interface WakeEvidenceProjection {
 }
 /** Capture the primary wake facts once and derive any number of eligibility decisions from them. */
 export declare function wakeEvidenceProjection(squarePath: string, now: number, env: NodeJS.ProcessEnv): Promise<WakeEvidenceProjection>;
-export declare function wakeEvidenceProjectionFromState(squarePath: string, state: SquareState, now: number, env: NodeJS.ProcessEnv, delivery?: DeliveryModel): WakeEvidenceProjection;
+export declare function wakeEvidenceProjectionFromState(squarePath: string, state: SquareState, now: number, env: NodeJS.ProcessEnv, delivery?: DeliveryModel): Promise<WakeEvidenceProjection>;
 /** Project every wake decision from the same primary evidence. */
 export declare function wakeEvidence(squarePath: string, recipient: string, actIndex: number, now: number, env: NodeJS.ProcessEnv): Promise<WakeEvidence>;
 export declare function wakeIsEligible(evidence: WakeEvidence): boolean;

package/dist/wake-evidence.js

@@ -8,13 +8,13 @@ import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
 import { observationFor } from './runtime.js';
 import { entryPresentation } from './views.js';
-function attentionKey(squarePath, recipient, actIndex) {
-    return JSON.stringify([canonicalSquarePath(squarePath), nameKey(recipient), actIndex]);
+async function attentionKey(squarePath, recipient, actIndex) {
+    return JSON.stringify([await canonicalSquarePath(squarePath), nameKey(recipient), actIndex]);
 }
-function projectionFromState(squarePath, state, now, env, delivery = deriveDeliveryModel(state)) {
-    const canonicalPath = canonicalSquarePath(squarePath);
+async function projectionFromState(squarePath, state, now, env, delivery = deriveDeliveryModel(state)) {
+    const canonicalPath = await canonicalSquarePath(squarePath);
     const owners = new Map();
-    for (const binding of readActiveBindings(now)) {
+    for (const binding of await readActiveBindings(now)) {
         if (binding.squarePath !== canonicalPath)
             continue;
         const key = nameKey(binding.name);
@@ -23,21 +23,21 @@ function projectionFromState(squarePath, state, now, env, delivery = deriveDeliv
         owners.set(key, recipientOwners);
     }
     const routesByOwner = new Map();
-    for (const route of readWakeRoutes({ freshOnly: true, now, env })) {
+    for (const route of await readWakeRoutes({ freshOnly: true, now, env })) {
         const routes = routesByOwner.get(route.ownerId) ?? [];
         routes.push(route);
         routesByOwner.set(route.ownerId, routes);
     }
     const attemptsByAttention = new Map();
-    for (const attempt of readWakeAttempts({ env, now })) {
-        const key = attentionKey(attempt.attention.squarePath, attempt.attention.recipient, attempt.attention.actIndex);
+    for (const attempt of await readWakeAttempts({ env, now })) {
+        const key = await attentionKey(attempt.attention.squarePath, attempt.attention.recipient, attempt.attention.actIndex);
         const attempts = attemptsByAttention.get(key) ?? [];
         attempts.push(attempt);
         attemptsByAttention.set(key, attempts);
     }
     const presentedByAttention = new Map();
-    for (const presented of readPresentedAttentions(env, now)) {
-        const key = attentionKey(presented.squarePath, presented.name, presented.actIndex);
+    for (const presented of await readPresentedAttentions(env, now)) {
+        const key = await attentionKey(presented.squarePath, presented.name, presented.actIndex);
         const presentedOwners = presentedByAttention.get(key) ?? new Set();
         presentedOwners.add(presented.ownerId);
         presentedByAttention.set(key, presentedOwners);
@@ -45,7 +45,7 @@ function projectionFromState(squarePath, state, now, env, delivery = deriveDeliv
     return {
         evidence(recipient, actIndex) {
             const recipientOwners = owners.get(nameKey(recipient)) ?? new Set();
-            const key = attentionKey(squarePath, recipient, actIndex);
+            const key = JSON.stringify([canonicalPath, nameKey(recipient), actIndex]);
             const attempts = attemptsByAttention.get(key) ?? [];
             const terminal = terminalWakeEvidence(attempts);
             const routes = [...recipientOwners].flatMap((ownerId) => routesByOwner.get(ownerId) ?? []);

package/dist/wake-port.d.ts

@@ -1,7 +1,7 @@
 import type { WakeAdapter, WakeDispatchResult } from './delivery.js';
 import type { WakeRoute } from './model.js';
 export interface WakePortHooks {
-    nextAttemptN(): number;
+    nextAttemptN(): number | Promise<number>;
     beforeSend(route: WakeRoute, attemptN: number): Promise<boolean>;
     record(route: WakeRoute, attemptN: number, result: Exclude<WakeDispatchResult, {
         outcome: 'cancelled' | 'unavailable';

package/dist/wake-port.js

@@ -9,7 +9,7 @@ export class WakePort {
             const adapter = this.adapters.get(route.kind);
             if (adapter === undefined)
                 continue;
-            const attemptN = hooks.nextAttemptN();
+            const attemptN = await hooks.nextAttemptN();
             const result = await adapter.dispatch(route.address, typeof payload === 'function' ? payload(route) : payload, () => hooks.beforeSend(route, attemptN));
             if (result.outcome === 'cancelled')
                 return result;

package/dist/watch.js

@@ -87,7 +87,7 @@ async function finishWatchResult(square, squarePath, name, result, leaseId, idle
 }
 async function beginWatch(square, squarePath, name, opts) {
     const id = leaseId();
-    const ownerId = localParticipantOwner(squarePath, name);
+    const ownerId = await localParticipantOwner(squarePath, name);
     return acquireWatchLease(square, name, id, opts, ownerId);
 }
 async function endWatch(square, name, id) {

package/extensions/square-pi.js

@@ -4,6 +4,12 @@ import { waitForSessionPending } from '../dist/inbox.js';
 import { lookupSessionBindings } from '../dist/registry.js';
 
 const PI_SEND_TIMEOUT_MS = 5_000;
+const DEFAULT_PI_BOUNDARY_TIMEOUT_MS = 2_000;
+
+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);
@@ -32,7 +38,18 @@ export default function squarePiExtension(pi) {
   let settledWaiters = [];
   const handledPending = new Set();
   let retryAfterChange = false;
-  const present = (deliver) => sessionId === undefined ? undefined : presentPendingAtBoundary(sessionId, deliver);
+  const present = (deliver, signal) => sessionId === undefined ? undefined : presentPendingAtBoundary(sessionId, deliver, undefined, undefined, signal);
+
+  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 waitForSettled = (serial, signal) => {
     if (settledSerial !== serial) return Promise.resolve();
@@ -67,7 +84,7 @@ export default function squarePiExtension(pi) {
 
   const wake = async (piContext, token, signal) => {
     while (sessionId !== undefined && token === generation && !signal.aborted) {
-      if (lookupSessionBindings(sessionId).length === 0) {
+      if ((await lookupSessionBindings(sessionId)).length === 0) {
         await pause(signal, 1_000);
         continue;
       }
@@ -103,6 +120,13 @@ export default function squarePiExtension(pi) {
             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);
                 }),
@@ -112,6 +136,9 @@ export default function squarePiExtension(pi) {
             }
             return true;
           },
+          undefined,
+          undefined,
+          signal,
         );
         if (delivered === true || delivered === undefined) {
           for (const key of keys) handledPending.add(key);
@@ -156,7 +183,7 @@ export default function squarePiExtension(pi) {
         return { message: { customType: 'square', content: context, display: true } };
       }
       if (presenting) return undefined;
-      return present((context) => ({ message: { customType: 'square', content: context, display: true } }));
+      return await presentAtBoundary((context) => ({ message: { customType: 'square', content: context, display: true } }));
     } catch {
       return undefined;
     }

package/package.json

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

package/skills/square/SKILL.md

@@ -74,11 +74,11 @@ EOF
 ```bash
 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 --mention   # filter to mentions
-square --location <square> --as <name> catch --from <names>
+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
 ```
 
-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.
+Every catch needs exactly one mode: `--now` or `--idle <duration>`. `--mention` and `--from` filter either mode; they do not replace it. 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