@astrosheep/square 0.4.4 → 0.4.5

package/dist/delivery-ledger.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { validateOwner } from './neutral.js';
 import { observeFileMetadata } from './file-changes.js';
 import { LedgerStore } from './delivery-ledger-sqlite.js';
+import { redactCurrentDiagnostic } from './diagnostic-redaction.js';
 function nonempty(value) {
     if (typeof value !== 'string' || value.length === 0)
         throw new TypeError('Expected a nonempty string');
@@ -59,6 +60,8 @@ function encodeDetails(details) {
 export class DeliveryLedger {
     store;
     leaseMs;
+    settlements = new Set();
+    retired = false;
     constructor(store, leaseMs) {
         this.store = store;
         this.leaseMs = leaseMs;
@@ -69,79 +72,103 @@ export class DeliveryLedger {
             throw new TypeError('Delivery location must be absolute');
         const leaseMs = options.leaseMs ?? 30_000;
         positive(leaseMs);
-        return new DeliveryLedger(await LedgerStore.open(location, options.clock ?? Date.now), leaseMs);
+        return new DeliveryLedger(await LedgerStore.open(location, options.clock ?? Date.now, options.signal), leaseMs);
     }
-    close() { return this.store.close(); }
-    attach(input) {
+    close() {
+        this.retired = true;
+        this.store.retire();
+        return this.settlements.size ? Promise.resolve() : this.store.close();
+    }
+    retainSettlement(handle) {
+        this.settlements.add(handle);
+        void handle.then(() => {
+            this.settlements.delete(handle);
+            if (this.retired && !this.settlements.size)
+                void this.store.close().catch(() => this.diagnose('delivery-ledger-deferred-close-error'));
+        });
+    }
+    diagnose(event, token, persistence) {
+        try {
+            const diagnostic = redactCurrentDiagnostic({ event, token, persistence });
+            try {
+                console.warn(diagnostic);
+            }
+            catch {
+                process.stderr.write(`${JSON.stringify(diagnostic)}\n`);
+            }
+        }
+        catch { /* Diagnostics cannot prevent resource retirement. */ }
+    }
+    attach(input, signal) {
         validateOwner(input.owner);
         routes(input.routes);
         if (input.expectedGeneration !== null)
             nonempty(input.expectedGeneration);
-        return this.store.attach(input);
+        return this.store.attach(input, signal);
     }
-    updateRoutes(input) {
+    updateRoutes(input, signal) {
         validateOwner(input.owner);
         nonempty(input.generation);
         routes(input.routes);
-        return this.store.updateRoutes(input);
+        return this.store.updateRoutes(input, signal);
     }
-    detach(input) { return this.lifecycle(input, 'detached'); }
-    markDeleted(input) { return this.lifecycle(input, 'deleted'); }
-    lifecycle(input, state) {
+    detach(input, signal) { return this.lifecycle(input, 'detached', signal); }
+    markDeleted(input, signal) { return this.lifecycle(input, 'deleted', signal); }
+    lifecycle(input, state, signal) {
         validateOwner(input.owner);
         nonempty(input.generation);
-        return this.store.lifecycle(input, state);
+        return this.store.lifecycle(input, state, signal);
     }
-    session(owner) { validateOwner(owner); return this.store.session(owner); }
-    sessions() { return this.store.sessions(); }
-    pending(owner, options) {
+    session(owner, signal) { validateOwner(owner); return this.store.session(owner, signal); }
+    sessions(signal) { return this.store.sessions(signal); }
+    pending(owner, options, signal) {
         validateOwner(owner);
         nonempty(options.generation);
-        return this.store.pendingCards(owner, options.generation);
+        return this.store.pendingCards(owner, options.generation, signal);
     }
-    handoffs(owner, options) {
+    handoffs(owner, options, signal) {
         validateOwner(owner);
         nonempty(options.generation);
-        return this.store.handoffs(owner, options.generation);
+        return this.store.handoffs(owner, options.generation, signal);
     }
-    post(input) {
+    post(input, signal) {
         validateOwner(input.owner);
         nonempty(input.key);
         if (typeof input.text !== 'string')
             throw new TypeError('Expected card text');
-        return this.store.post({ ...input, details: input.details === undefined ? null : encodeDetails(input.details) });
+        return this.store.post({ ...input, details: input.details === undefined ? null : encodeDetails(input.details) }, signal);
     }
-    suppress(input) {
+    suppress(input, signal) {
         validateOwner(input.owner);
         nonempty(input.key);
         if (!['exact', 'prefix'].includes(input.scope) || input.expiresAt !== undefined && !Number.isFinite(input.expiresAt))
             throw new TypeError('Invalid suppression');
-        return this.store.suppress(input);
+        return this.store.suppress(input, signal);
     }
-    renewSuppression(input) {
+    renewSuppression(input, signal) {
         validateOwner(input.owner);
         nonempty(input.id);
         if (!Number.isFinite(input.expiresAt))
             throw new TypeError('Expected finite suppression expiry');
-        return this.store.renewSuppression(input);
+        return this.store.renewSuppression(input, signal);
     }
-    releaseSuppression(input) {
+    releaseSuppression(input, signal) {
         validateOwner(input.owner);
         nonempty(input.id);
-        return this.store.releaseSuppression(input);
+        return this.store.releaseSuppression(input, signal);
     }
-    cancel(input) {
+    cancel(input, signal) {
         validateOwner(input.owner);
         nonempty(input.generation);
-        return this.store.cancel(input);
+        return this.store.cancel(input, signal);
     }
-    receipts(owner, options = {}) {
+    receipts(owner, options = {}, signal) {
         validateOwner(owner);
         if (options.keys)
             options.keys.forEach(nonempty);
         if (options.since !== undefined && !Number.isFinite(options.since))
             throw new TypeError('Expected finite receipt time');
-        return this.store.receipts(owner, options);
+        return this.store.receipts(owner, options, signal);
     }
     async claimPresentation(owner, options) {
         validateOwner(owner);
@@ -158,27 +185,27 @@ export class DeliveryLedger {
             settle: outcome => {
                 if (!['presented', 'failed', 'unknown', 'released'].includes(outcome))
                     throw new TypeError('Invalid presentation outcome');
-                return this.store.settle(tokens, outcome);
+                return this.store.settle(tokens, outcome, AbortSignal.timeout(5000));
             },
         };
     }
     /** Resolve the original prepared handoff, including its stored route kind. */
-    handoff(token) {
+    handoff(token, signal) {
         nonempty(token);
-        return this.store.handoff(token);
+        return this.store.handoff(token, signal);
     }
-    guardHandoff(ref) { return this.store.guardHandoff(ref); }
-    acceptHandoff(ref) { return this.store.acceptHandoff(ref); }
+    guardHandoff(ref, signal) { return this.store.guardHandoff(ref, signal); }
+    acceptHandoff(ref, signal) { return this.store.acceptHandoff(ref, signal); }
     /** Confirms the exact existing external effect; never sends or returns text. */
-    observePresentation(handoff, options) {
+    observePresentation(handoff, options, signal) {
         if (typeof handoff === 'string')
             nonempty(handoff);
-        return this.store.observePresentation(handoff, options);
+        return this.store.observePresentation(handoff, options, signal);
     }
-    health(owner) {
+    health(owner, signal) {
         if (owner !== undefined)
             validateOwner(owner);
-        return this.store.health(owner);
+        return this.store.health(owner, signal);
     }
     /** Subscribe first; read the returned version, inspect state, then await changed(version,...). */
     observe(owner) {
@@ -193,76 +220,118 @@ export class DeliveryLedger {
         if (options.signal?.aborted)
             return { outcome: 'not-invoked' };
         nonempty(transport.kind);
-        const claim = await this.store.claimHandoff(owner, key, options.generation, transport.kind, Math.max(this.leaseMs, options.timeoutMs), options.signal);
-        if (!claim)
-            return { outcome: 'not-invoked' };
-        const token = claim.attempt.token;
+        const lifetime = Promise.withResolvers();
+        this.retainSettlement(lifetime.promise);
+        // One deadline includes acquisition, validation, preparation and the external effect.
+        const deadline = Date.now() + options.timeoutMs;
         const controller = new AbortController();
         const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
-        const deadline = Date.now() + options.timeoutMs;
-        let persistenceFailure;
-        const persist = async (operation) => {
+        const timer = setTimeout(() => controller.abort(new Error('Delivery deadline elapsed')), options.timeoutMs);
+        let onAbort;
+        try {
+            let claim;
             try {
-                return await operation;
+                claim = await this.store.claimHandoff(owner, key, options.generation, transport.kind, Math.max(this.leaseMs, options.timeoutMs), signal);
             }
             catch (error) {
-                persistenceFailure = { error };
+                if (signal.aborted && error === signal.reason)
+                    return { outcome: 'not-invoked' };
                 throw error;
             }
-        };
-        const current = () => persist(this.store.current([token], signal, claim.route));
-        const finish = async (outcome) => {
-            if (!['accepted', 'presented', 'failed', 'unknown', 'not-capable', 'released'].includes(outcome))
-                throw new TypeError('Invalid transport outcome');
-            const recorded = await this.store.settle([token], outcome === 'not-capable' ? 'released' : outcome);
-            if (persistenceFailure)
-                throw persistenceFailure.error;
-            return { outcome, token, persistence: recorded ? 'recorded' : 'not-recorded' };
-        };
-        if (!await current() || signal.aborted || Date.now() >= deadline)
-            return finish('released');
-        let timer;
-        let onAbort;
-        try {
+            if (!claim)
+                return { outcome: 'not-invoked' };
+            const token = claim.attempt.token;
+            let persistenceFailure;
+            const persist = async (operation) => {
+                try {
+                    return await operation;
+                }
+                catch (error) {
+                    if (!signal.aborted || error !== signal.reason)
+                        persistenceFailure = { error };
+                    throw error;
+                }
+            };
+            const current = () => persist(this.store.current([token], signal, claim.route));
+            const finish = async (outcome) => {
+                if (!['accepted', 'presented', 'failed', 'unknown', 'not-capable', 'released'].includes(outcome))
+                    throw new TypeError('Invalid transport outcome');
+                const recorded = await this.store.settle([token], outcome === 'not-capable' ? 'released' : outcome, AbortSignal.timeout(5000));
+                return { outcome, token, persistence: recorded ? 'recorded' : 'not-recorded' };
+            };
+            let eligible;
+            try {
+                eligible = await current();
+            }
+            catch (error) {
+                const released = await finish('released');
+                if (signal.aborted && error === signal.reason)
+                    return released;
+                throw error;
+            }
+            if (this.retired || !eligible || signal.aborted || Date.now() >= deadline)
+                return await finish('released');
             const interrupted = new Promise(resolve => {
                 onAbort = () => resolve('unknown');
                 signal.addEventListener('abort', onAbort, { once: true });
-                timer = setTimeout(() => { resolve('unknown'); controller.abort(new Error('Delivery deadline elapsed')); }, options.timeoutMs);
+                if (signal.aborted)
+                    onAbort();
             });
-            // Invoke synchronously after the final fence; adapters own checks after their own awaits.
-            const effect = (async () => {
-                if (signal.aborted || Date.now() >= deadline)
-                    return 'released';
-                return transport.send(claim.card, claim.route.address, { token, deadline, signal,
-                    beforeSend: current,
-                    prepare: value => { correlation(value); return persist(this.store.prepare(token, value, signal)); },
-                });
-            })().catch(() => 'unknown');
+            // No await separates the final fence from invocation. Adapters fence their own awaits.
+            const effect = (async () => transport.send(claim.card, claim.route.address, { token, deadline, signal,
+                beforeSend: current,
+                prepare: value => { correlation(value); return persist(this.store.prepare(token, value, signal)); },
+            }))().catch(() => 'unknown');
             const first = await Promise.race([
                 effect.then(outcome => ({ outcome, interrupted: false })),
                 interrupted.then(outcome => ({ outcome, interrupted: true })),
             ]);
-            if (!first.interrupted)
-                return await finish(first.outcome);
+            if (!first.interrupted) {
+                const result = await finish(first.outcome);
+                if (persistenceFailure)
+                    throw persistenceFailure.error;
+                return result;
+            }
+            // Register the effect followup even if the initial unknown write fails. Its
+            // captured connection survives caller close; no new send authority is granted.
             const unknown = finish('unknown');
-            // Register before awaiting persistence; even an already completed effect waits for unknown.
-            const lateSettlement = unknown.then(async () => {
+            let unknownRecorded = false;
+            const initial = unknown.then(result => { unknownRecorded = result.persistence === 'recorded'; return result; });
+            const lateSettlement = initial.catch(() => undefined).then(async () => {
                 const outcome = await effect;
                 try {
-                    const result = await finish(outcome);
-                    return { outcome, persistence: { status: result.persistence } };
+                    // A late negative cannot release an interrupted effect whose unknown
+                    // evidence failed to persist. Keep conservative custody in that case.
+                    const negative = ['failed', 'not-capable', 'released'].includes(outcome);
+                    const result = await finish(!unknownRecorded && negative ? 'unknown' : outcome);
+                    return { outcome, persistence: { status: !unknownRecorded && negative ? 'not-recorded' : result.persistence } };
                 }
                 catch (error) {
                     return { outcome, persistence: { status: 'error', error } };
                 }
-            }, error => ({ outcome: 'unknown', persistence: { status: 'error', error } }));
-            return { ...await unknown, lateSettlement };
+            });
+            // The ledger owns retention on rejection too: callers cannot track a result
+            // they never received. Surface the original error while retaining late evidence.
+            this.retainSettlement(lateSettlement);
+            try {
+                const result = await initial;
+                if (persistenceFailure)
+                    throw persistenceFailure.error;
+                return { ...result, lateSettlement };
+            }
+            catch (error) {
+                void lateSettlement.then(result => {
+                    if (result.persistence.status !== 'recorded')
+                        this.diagnose('delivery-late-settlement', token, result.persistence.status);
+                });
+                throw error;
+            }
         }
         finally {
-            if (timer !== undefined)
-                clearTimeout(timer);
+            clearTimeout(timer);
             if (onAbort)
                 signal.removeEventListener('abort', onAbort);
+            lifetime.resolve();
         }
     }
 }

package/dist/delivery-lifetime.d.ts

@@ -1,6 +1,6 @@
 import type { DeliveryLedger, HandoffResult } from './delivery-ledger.js';
-/** Retire the caller's connection without abandoning an already-invoked effect. */
+/** Report late evidence; DeliveryLedger alone owns connection retirement. */
 export declare function retainDeliveryLedger(ledger: DeliveryLedger): {
     track(result: HandoffResult): void;
-    close(): Promise<void>;
+    close: () => Promise<void>;
 };

package/dist/delivery-lifetime.js

@@ -1,8 +1,8 @@
 import { redactCurrentDiagnostic } from './diagnostic-redaction.js';
-/** Retire the caller's connection without abandoning an already-invoked effect. */
+/** Report late evidence; DeliveryLedger alone owns connection retirement. */
 export function retainDeliveryLedger(ledger) {
-    const pending = new Set();
-    let retired = false, closing;
+    const tracked = new WeakSet();
+    let closing;
     const diagnose = (event, result, detail) => {
         try {
             const diagnostic = redactCurrentDiagnostic({ event, token: result?.token, outcome: result?.outcome, ...detail });
@@ -15,31 +15,19 @@ export function retainDeliveryLedger(ledger) {
         }
         catch { /* Closed diagnostic sinks cannot prevent settlement or resource retirement. */ }
     };
-    const closeOnce = () => closing ??= ledger.close();
-    const settled = (handle) => {
-        pending.delete(handle);
-        if (retired && !pending.size)
-            void closeOnce().catch(() => diagnose('delivery-ledger-deferred-close-error'));
-    };
     return {
         track(result) {
             const handle = result.lateSettlement;
-            if (!handle || pending.has(handle))
+            if (!handle || tracked.has(handle))
                 return;
-            pending.add(handle);
+            tracked.add(handle);
             void handle.then(late => {
                 if (late.persistence.status !== 'recorded')
                     diagnose('delivery-late-settlement', result, { lateOutcome: late.outcome, persistence: late.persistence.status });
-                settled(handle);
             }, () => {
                 diagnose('delivery-late-settlement-rejected', result);
-                settled(handle);
             });
         },
-        async close() {
-            retired = true;
-            if (!pending.size)
-                await closeOnce();
-        },
+        close: () => closing ??= ledger.close(),
     };
 }

package/dist/help.js

@@ -2,14 +2,14 @@ import { JSON_COMMANDS } from './cli/json.js';
 const COMMANDS = [
     { names: ['help'], usage: 'help [command]', summary: 'Show the command index or help for one command.' },
     { names: ['version'], usage: 'version', summary: 'Print the installed version.', hiddenFromIndex: true },
-    { names: ['mcp-server'], usage: 'mcp-server', summary: 'Start the MCP stdio server.', usesSquare: true, hiddenFromIndex: true, details: ['Set SQUARE_LOCATION or pass --location before the command.', 'Participant tools accept as on each call. Set the default with --as.', 'Session identity comes from request _meta.threadId (Codex) or _meta["ai.opencode/sessionID"] (OpenCode), falling back to the startup environment.'] },
+    { names: ['mcp-server'], usage: 'mcp-server', summary: 'Start the MCP stdio server.', hiddenFromIndex: true, details: ['Use list to find nearby squares; single-square tools require location on each call.', 'Participant tools accept as on each call; join requires an explicit name.', 'Session identity comes from request _meta.threadId (Codex) or _meta["ai.opencode/sessionID"] (OpenCode), falling back to the startup environment.'] },
     {
         names: ['build'], usage: 'build [--cap <N|unlimited>] [--template <name>] [--throttle N] [-f] < body.md', usesSquare: true, group: 'host',
         summary: 'Create a square from Markdown on stdin.',
         details: ['Options:', '  --cap <N|unlimited>  Set a per-participant activity cap (default unlimited).', '  --template <name>    Append a packaged activity guide.', '  --throttle <N>       Allow at most N public activities per minute.', '  -f, --force          Replace an existing artifact.'],
     },
     {
-        names: ['list', 'ls'], usage: '{command} [--depth N] [--limit N] [--after path]', summary: 'List nearby squares below the current directory.', group: 'host',
+        names: ['list', 'ls'], usage: '{command} [--depth N] [--limit N] [--after path]', summary: 'List nearby squares and your joined names with waiting activity counts.', group: 'host',
         details: ['Options:', '  --depth <N>    Descend through at most N directory levels (default 4; maximum 16; 0 scans only the current directory).', '  --limit <N>    Show one page (default 20, maximum 100).', '  --after <path> Resume after a relative path from a previous page.'],
     },
     {
@@ -31,7 +31,7 @@ const COMMANDS = [
             '  Bare activities are delivered only to participants listening to the sender.',
             '',
             'Options:',
-            '  -f, --force       Express without first catching unread activity or satisfying attention etiquette.',
+            '  -f, --force       Express without first perceiving unread activity or satisfying attention etiquette.',
             '  --no-wait         If throttled, save a draft and return instead of waiting.',
             '  --metadata <json> Attach a bounded JSON object (at most 16 KiB UTF-8 and 256 nesting levels); it may be the only content.',
             '                    Metadata is returned in structured activity results but is not shown in human text or searchable.',
@@ -42,14 +42,14 @@ const COMMANDS = [
     { names: ['ignore'], usage: '--as <name> ignore <participant>', usesSquare: true, group: 'participant', summary: 'Stop hearing one participant\'s future activity, except bells.' },
     { names: ['listening'], usage: '--as <name> listening', usesSquare: true, group: 'participant', summary: 'Show who you are turned toward.', details: ['Listening applies to future activity. What you could hear when an activity landed does not change afterward.'] },
     {
-        names: ['catch'], usage: '--as <name> catch [--id <activity-id>] [--now | --idle <duration>] [--from <names>] [--mention] [--limit <count>] [--replace]', usesSquare: true, group: 'participant',
-        summary: 'Catch directed conversation since you last looked.',
-        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; bare catch already does this.', '  --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: ['perceive'], usage: '--as <name> perceive [--id <activity-id>] [--now | --idle <duration>] [--from <names>] [--mention] [--limit <count>] [--replace]', usesSquare: true, group: 'participant',
+        summary: 'Perceive directed conversation since you last looked.',
+        details: ['Modes:', '  --id <activity-id> Perceive 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; perceive --id consumes the selected activity.', '  --now             Take in activity immediately; bare perceive already does this.', '  --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 perceive for this participant.'],
     },
     { names: ['done'], usage: '--as <name> done', usesSquare: true, group: 'participant', summary: 'Step out of the square.', details: ['done takes no message. Use express before leaving to send one.'] },
     {
         names: ['stream'], usage: 'stream [--ndjson [--for <name>] [--last <N> | --after <id>]]', usesSquare: true, hiddenFromIndex: true,
-        summary: 'Follow activity without marking it caught.',
+        summary: 'Follow activity without marking it perceived.',
         details: ['Options:', '  --ndjson       Emit one JSON event per line.', '  --for <name>   With --ndjson, emit notifications for one participant.', '  --last <N>     Emit the last N eligible activities first (default 10, maximum 100).', '  --after <id>   Resume after a canonical activity id (act/12).'],
     },
     {
@@ -64,7 +64,7 @@ const COMMANDS = [
     { names: ['claude-watch'], usage: '{command}', summary: 'Observe pending attention from a native async Stop hook.', hiddenFromIndex: true },
     {
         names: ['history'], usage: 'history [filters] [output]', usesSquare: true, group: 'participant',
-        summary: 'Read or search the archive without changing what you have caught.',
+        summary: 'Read or search the archive without changing what you have perceived.',
         details: ['Optional --as is accepted but does not change the archive or claim a name.', '', 'Filters:', '  --from <names>                  Match activities from participants.', '  --since <time>                  Match activities after a time.', '  --grep <regex> | --fixed <s>    Search activity ids, participants, and original bodies.', '  --mention <name>                Match direct attention for a participant.', '  --at <ids>                      Center on comma-separated activity ids; may repeat.', '  -B, -A, -C <N>                 Set non-negative context around every --at coordinate.', '  --before <id>                   Read the page immediately before an activity.', '  --after <id>                    Read the page immediately after an activity.', '', 'Results:', '  --limit <N>                     Page size (default 10, maximum 100).', '  --order <asc|desc>              Set display order (default oldest first).', '', 'Output:', '  --no-truncate  --json  --format <fields>', '  One result shows its full body; multiple results use previews.', '  --no-truncate shows every original body.'],
     },
     { names: ['status'], usage: '[--as <name>] status', usesSquare: true, group: 'participant', summary: 'Show who is present and what happened most recently.' },
@@ -101,7 +101,7 @@ function isHelpFlag(value) {
 }
 export function renderGlobalHelp() {
     const groups = [
-        { key: 'participant', title: 'In the square:', order: ['join', 'express', 'listen', 'unlisten', 'ignore', 'listening', 'catch', 'history', 'status', 'done'] },
+        { key: 'participant', title: 'In the square:', order: ['join', 'express', 'listen', 'unlisten', 'ignore', 'listening', 'perceive', 'history', 'status', 'done'] },
         { key: 'host', title: 'Prepare and manage:', order: ['build', 'list', 'participants'] },
         { key: 'maintenance', title: 'Setup:', order: ['install', 'uninstall', 'doctor'] },
     ];
@@ -115,9 +115,9 @@ export function renderGlobalHelp() {
     ]);
     return [
         'Usage: square [--location <square>] [--as <name>] [--owner <id>] <command> [args...]',
-        'Environment: SQUARE_LOCATION sets the CLI local artifact path; square-accessing commands require it or --location. Use --as to select a participant.',
-        'Identity: --owner overrides SQUARE_OWNER, then a complete harness identity, then user:<OS user>@<host>. Incomplete or ambiguous harness identities refuse. Owners without wake use catch --idle.',
-        'Output: --json on join, express, catch, history, listen, ignore, unlisten, listening, done, status, participants and inbox prints the SDK result without observation; a participant handle becomes {name}.',
+        'Location: square-accessing commands require --location <square>. Use square list to find nearby squares and your joined names; use --as to select a participant.',
+        'Identity: --owner overrides SQUARE_OWNER, then a complete harness identity, then user:<OS user>@<host>. Incomplete or ambiguous harness identities refuse. Owners without wake use perceive --idle.',
+        'Output: --json on join, express, perceive, history, listen, ignore, unlisten, listening, done, status, participants and inbox prints the SDK result without observation; a participant handle becomes {name}.',
         'History emits one JSON document; stream --ndjson emits one SDK record per line.',
         '',
         ...commandLines,

package/dist/hints.d.ts

@@ -1,4 +1,4 @@
 /** First activity, then every fifth. */
 export declare function expressHint(ownActivityCount: number): string | undefined;
-/** First caught activity, then each time the caught total crosses another ten. */
-export declare function catchHint(caughtBefore: number, caughtAfter: number): string | undefined;
+/** First perceived activity, then each time the perceived total crosses another ten. */
+export declare function perceiveHint(perceivedBefore: number, perceivedAfter: number): string | undefined;

package/dist/hints.js

@@ -4,9 +4,9 @@ const EXPRESS_HINTS = [
     "answer someone's actual words — they're standing right there",
     "say the half-shaped thing — that's what the square is for",
 ];
-const CATCH_HINTS = [
+const PERCEIVE_HINTS = [
     'want to follow one voice? listen to them; unlisten once you have heard enough',
-    "nothing to add? quiet is fine — catching is listening too",
+    "nothing to add? quiet is fine — perceiving is listening too",
     "no need to reply just to say you’ve read a message — Square already tracks that",
     'reply to an activity to reach the person who spoke',
 ];
@@ -16,10 +16,10 @@ export function expressHint(ownActivityCount) {
         return undefined;
     return EXPRESS_HINTS[Math.floor(ownActivityCount / 5) % EXPRESS_HINTS.length];
 }
-/** First caught activity, then each time the caught total crosses another ten. */
-export function catchHint(caughtBefore, caughtAfter) {
-    if (caughtAfter <= caughtBefore)
+/** First perceived activity, then each time the perceived total crosses another ten. */
+export function perceiveHint(perceivedBefore, perceivedAfter) {
+    if (perceivedAfter <= perceivedBefore)
         return undefined;
-    const crossed = caughtBefore === 0 || Math.floor(caughtAfter / 10) > Math.floor(caughtBefore / 10);
-    return crossed ? CATCH_HINTS[Math.floor(caughtAfter / 10) % CATCH_HINTS.length] : undefined;
+    const crossed = perceivedBefore === 0 || Math.floor(perceivedAfter / 10) > Math.floor(perceivedBefore / 10);
+    return crossed ? PERCEIVE_HINTS[Math.floor(perceivedAfter / 10) % PERCEIVE_HINTS.length] : undefined;
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare } from './square-api.js';
+export { Square, squareLocation, squareClock, discover, inbox, diagnoseSquare } from './square-api.js';
 export { SquareError, ACTIVITY_METADATA_MAX_BYTES } from './model.js';
 export { selectOwnSeat, requireOwner, requireJoinName, localUserOwner, harnessOwner, decodeHarnessOwner } from './square-api.js';
 export { postAndDispatch, dispatchEligibleCards } from './notifications.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare } from './square-api.js';
+export { Square, squareLocation, squareClock, discover, inbox, diagnoseSquare } from './square-api.js';
 export { SquareError, ACTIVITY_METADATA_MAX_BYTES } from './model.js';
 export { selectOwnSeat, requireOwner, requireJoinName, localUserOwner, harnessOwner, decodeHarnessOwner } from './square-api.js';
 export { postAndDispatch, dispatchEligibleCards } from './notifications.js';

package/dist/list.d.ts

@@ -1,7 +1,7 @@
-import type { DiscoveryResult, DiscoveryOptions, OpenOptions, OperationControl } from './square-facade.js';
+import type { DiscoveryResult, DiscoveryOptions, OperationControl } from './square-facade.js';
 export declare const DEFAULT_LIST_DEPTH = 4;
 export declare const MAX_LIST_DEPTH = 16;
 export declare const DEFAULT_LIST_LIMIT = 20;
 export declare const MAX_LIST_LIMIT = 100;
 /** Bounded deterministic discovery for the public resource API. */
-export declare function discoverSquares(root: string, options?: DiscoveryOptions, control?: OperationControl, openOptions?: OpenOptions): Promise<DiscoveryResult>;
+export declare function discoverSquares(root: string, options?: DiscoveryOptions, control?: OperationControl): Promise<DiscoveryResult>;

package/dist/list.js

@@ -18,7 +18,7 @@ async function readSquareListItem(filePath, root, options, control) {
         const artifact = createArtifactPort(filePath, undefined, control?.signal);
         let projection;
         try {
-            projection = (await artifact.read(listPresentation, control?.signal)).value;
+            projection = (await artifact.read(facts => listPresentation(facts, options.owner), control?.signal)).value;
         }
         finally {
             await artifact.close();
@@ -29,6 +29,7 @@ async function readSquareListItem(filePath, root, options, control) {
             context: [...projection.context].map((line) => line.trim()).filter(Boolean),
             participants: [...projection.participants],
             activities: projection.activities,
+            ...(projection.joined === undefined ? {} : { joined: projection.joined }),
         };
     }
     catch (error) {
@@ -38,7 +39,7 @@ async function readSquareListItem(filePath, root, options, control) {
     }
 }
 /** Bounded deterministic discovery for the public resource API. */
-export async function discoverSquares(root, options = {}, control, openOptions = {}) {
+export async function discoverSquares(root, options = {}, control) {
     const depth = options.depth ?? DEFAULT_LIST_DEPTH;
     const limit = options.limit ?? DEFAULT_LIST_LIMIT;
     if (!Number.isSafeInteger(depth) || depth < 0 || depth > MAX_LIST_DEPTH
@@ -74,7 +75,7 @@ export async function discoverSquares(root, options = {}, control, openOptions =
                     await walk(fullPath, level + 1);
             }
             else if (entry.isFile()) {
-                const item = await readSquareListItem(fullPath, root, openOptions, control);
+                const item = await readSquareListItem(fullPath, root, options, control);
                 if (item !== null)
                     items.push(item);
             }

package/dist/mcp.d.ts

@@ -2,8 +2,8 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Owner } from './square-api.js';
 import type { SquareAtInput } from './square-facade.js';
 import type { WakeAddress } from './model.js';
-/** The server owns its artifact connection lifetime, so callers cannot lend one. */
-export interface SquareMcpOptions extends Omit<SquareAtInput, 'resources'> {
+/** Each tool call chooses its square and owns its connection lifetime. */
+export interface SquareMcpOptions extends Omit<SquareAtInput, 'path'> {
     readonly owner?: Owner;
     readonly wakeAddress?: WakeAddress;
 }