@astrosheep/square 0.3.72 → 0.3.74

package/dist/inbox.d.ts

@@ -36,6 +36,8 @@ export type NativePendingPreviewInput = {
 export declare function nativePendingPreview(facts: SquareRead, input: NativePendingPreviewInput): NativePendingPreview | undefined;
 export declare function sessionInbox(sessionId: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<InboxMembership[]>;
 export interface SessionPendingObserver {
+    /** Read committed revisions before reusing content; filesystem hints are only for waiting. */
+    read(options?: Pick<PendingWaitOptions, 'signal' | 'excludeKeys'>): Promise<InboxMembership[]>;
     wait(timeoutMs: number, options?: PendingWaitOptions): Promise<InboxMembership[]>;
     close(): void;
 }

package/dist/inbox.js

@@ -109,7 +109,66 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
     const ledger = await hostLedger.observeChanges();
     const artifacts = new Map();
     const lifetime = new AbortController();
+    const bindingsNow = async () => Promise.all((await projectSessionBindings({ hostLedger, sessionId })).map(async (binding) => ({ ...binding, location: await canonicalPath(binding.location) })));
+    async function membershipAt(binding, version, signal) {
+        const cache = artifacts.get(binding.location)?.inbox;
+        const name = nameKey(binding.participant);
+        const coordinate = bindingCoordinate(binding);
+        let cached = cache?.get(name);
+        if (cached === undefined || cached.version !== version || cached.binding !== coordinate) {
+            cached = { ...await readInboxMembership(binding, signal), binding: coordinate };
+            cache?.set(name, cached);
+        }
+        const membership = cached.value;
+        if (membership === undefined)
+            return undefined;
+        const { catchLease, ...rest } = membership;
+        const now = Date.now();
+        return catchLease !== undefined && catchLease.expiresAt > now && now - catchLease.heartbeatAt <= WATCH_STALE_MS
+            ? membership : rest;
+    }
+    async function eligibleInbox(inbox, excludeKeys) {
+        const eligible = await projectBoundaryEligibility({ hostLedger, sessionId, inbox });
+        return excludeKeys === undefined ? eligible : eligible.flatMap((membership) => {
+            const notifications = membership.notifications.filter((notification) => !excludeKeys.has(notificationKey(membership, notification.actIndex)));
+            return notifications.length === 0 ? [] : [{ ...membership, notifications }];
+        });
+    }
     return {
+        async read(options = {}) {
+            const signal = AbortSignal.any([lifetime.signal, ...(options.signal === undefined ? [] : [options.signal])]);
+            signal.throwIfAborted();
+            const bindings = await bindingsNow();
+            const revisions = new Map();
+            const inbox = [];
+            for (const binding of bindings) {
+                signal.throwIfAborted();
+                try {
+                    let version = revisions.get(binding.location);
+                    if (version === undefined) {
+                        const artifact = createArtifactPort(binding.location);
+                        try {
+                            version = await artifact.revision(signal);
+                        }
+                        finally {
+                            await artifact.close();
+                        }
+                        revisions.set(binding.location, version);
+                    }
+                    const membership = await membershipAt(binding, version, signal);
+                    if (membership !== undefined)
+                        inbox.push(membership);
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        throw signal.reason ?? error;
+                    // An unreadable current revision must never authorize cached content.
+                }
+            }
+            const pending = await eligibleInbox(inbox, options.excludeKeys);
+            signal.throwIfAborted();
+            return pending;
+        },
         async wait(timeoutMs, options = {}) {
             const deadline = Date.now() + Math.max(0, timeoutMs);
             const expired = new AbortController();
@@ -123,7 +182,7 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
                 while (!signal.aborted) {
                     // Subscribe/capture the ledger BEFORE discovering bindings; a concurrent join cannot fall in a gap.
                     const sources = await Promise.all([capture(ledger.presence, 'presence', signal), capture(ledger.evidence, 'evidence', signal)]);
-                    const bindings = await Promise.all((await projectSessionBindings({ hostLedger, sessionId })).map(async (binding) => ({ ...binding, location: await canonicalPath(binding.location) })));
+                    const bindings = await bindingsNow();
                     const paths = new Set(bindings.map((binding) => binding.location));
                     for (const [file, entry] of artifacts) {
                         if (!paths.has(file)) {
@@ -155,22 +214,10 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
                     for (const binding of bindings) {
                         if (signal.aborted)
                             return [];
-                        const entry = artifacts.get(binding.location);
-                        const name = nameKey(binding.participant);
                         try {
-                            const coordinate = bindingCoordinate(binding);
-                            const cached = entry.inbox.get(name);
-                            if (cached?.version !== revisions.get(binding.location) || cached?.binding !== coordinate) {
-                                const projection = await readInboxMembership(binding, signal);
-                                entry.inbox.set(name, { ...projection, binding: coordinate });
-                            }
-                            const membership = entry.inbox.get(name)?.value;
-                            if (membership === undefined)
-                                continue;
-                            const { catchLease, ...rest } = membership;
-                            const now = Date.now();
-                            inbox.push(catchLease !== undefined && catchLease.expiresAt > now && now - catchLease.heartbeatAt <= WATCH_STALE_MS
-                                ? membership : rest);
+                            const membership = await membershipAt(binding, revisions.get(binding.location), signal);
+                            if (membership !== undefined)
+                                inbox.push(membership);
                         }
                         catch (error) {
                             if (signal.aborted)
@@ -178,12 +225,7 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
                             // Unreadable projections are retried, never cached as current.
                         }
                     }
-                    const eligible = await projectBoundaryEligibility({ hostLedger, sessionId, inbox });
-                    const excludeKeys = options.excludeKeys;
-                    const pending = excludeKeys === undefined ? eligible : eligible.flatMap((membership) => {
-                        const notifications = membership.notifications.filter((notification) => !excludeKeys.has(notificationKey(membership, notification.actIndex)));
-                        return notifications.length === 0 ? [] : [{ ...membership, notifications }];
-                    });
+                    const pending = await eligibleInbox(inbox, options.excludeKeys);
                     const eligibleKeys = JSON.stringify(pending.flatMap((membership) => membership.notifications.map((note) => notificationKey(membership, note.actIndex))).sort());
                     if (previousEligible !== undefined && previousEligible !== eligibleKeys)
                         canReturn = true;

package/dist/ledger-maintenance.d.ts

@@ -0,0 +1,30 @@
+import type { HostLedgerPort } from './host-ledger.js';
+/** The two host-ledger capabilities maintenance uses; no parallel ledger contract is owned here. */
+type MaintenanceLedger = Pick<HostLedgerPort, 'listEvidence' | 'retireEvidenceIfUnchanged'>;
+export interface LedgerMaintenanceOptions {
+    /** Prove eligible rows without retiring anything. */
+    readonly dryRun?: boolean;
+    readonly now?: number;
+}
+/**
+ * Counts are retired rows, not reclaimed bytes: SQLite reuses freed storage without necessarily
+ * shrinking its file. Retired Claude correlations leave indefinite recognition tokens; total
+ * token count remains unbounded. Maintenance does not run VACUUM.
+ */
+export interface LedgerMaintenanceReport {
+    readonly dryRun: boolean;
+    /** Old rows whose closure proof passed; exact-record CAS may still refuse. */
+    readonly eligible: number;
+    /** Rows actually removed by this run; always 0 in a dry run. */
+    readonly retired: number;
+    /** Eligible rows whose full-record compare-and-swap refused; always 0 in a dry run. */
+    readonly casMisses: number;
+    /** Canonical locations whose artifact could not be read; their rows were retained. */
+    readonly unavailableArtifacts: readonly string[];
+}
+/** Command/application entry: root selection uses the caller's captured environment. */
+export declare function gcHostLedger(options?: LedgerMaintenanceOptions & {
+    readonly env?: NodeJS.ProcessEnv;
+}): Promise<LedgerMaintenanceReport>;
+export declare function maintainHostLedger(ledger: MaintenanceLedger, options?: LedgerMaintenanceOptions): Promise<LedgerMaintenanceReport>;
+export {};

package/dist/ledger-maintenance.js

@@ -0,0 +1,110 @@
+import { createArtifactPort } from './artifact.js';
+import { canonicalPath } from './canonical-path.js';
+import { formatActivityId, parseActivityId } from './square-core.js';
+import { validateName } from './model.js';
+import { hostLedgerForEnv } from './registry.js';
+/**
+ * Explicit host-ledger evidence maintenance.
+ *
+ * Old wake/presentation rows are retired only when a typed artifact snapshot proves the
+ * recipient's attention is permanently closed: the activity reached them historically, and
+ * either catch recorded a receipt or the recipient joined again past it. Everything else is
+ * retained. Artifacts are read directly, one snapshot per canonical location, outside any
+ * ledger lock; retirement is the ledger's exact-record compare-and-swap. No SQL lives here.
+ */
+/** A row is old enough to consider once its landing time is at least this far behind now. */
+const RETIREMENT_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+/** The canonical activity coordinate the row names; leading zeros and other spellings are invalid. */
+function activityIndex(activity) {
+    const index = parseActivityId(activity);
+    return index === undefined || formatActivityId(index) !== activity ? undefined : index;
+}
+/** Old, durably closed-looking wake/presentation rows with usable coordinates. */
+function isCandidate(record, now) {
+    if (record.kind !== 'wake' && record.kind !== 'presentation')
+        return false;
+    if (record.outcome === 'dispatching')
+        return false;
+    if (typeof record.at !== 'number' || !Number.isFinite(record.at) || record.at > now - RETIREMENT_AGE_MS)
+        return false;
+    if (typeof record.location !== 'string' || record.location.length === 0)
+        return false;
+    try {
+        validateName(record.participant);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+/**
+ * One artifact snapshot for one location either proves each candidate closed or reports the
+ * whole location unavailable. A missing, unreadable, or non-artifact path returns undefined
+ * and its rows are retained.
+ */
+async function provenClosable(location, group) {
+    const artifact = createArtifactPort(location);
+    try {
+        return (await artifact.read((facts) => group.filter((candidate) => {
+            const participant = candidate.record.participant;
+            if (facts.directedAt(participant, candidate.index) === undefined)
+                return false;
+            if (facts.receipt(participant, candidate.index) !== undefined)
+                return true;
+            const lastJoin = facts.participant(participant)?.lastJoinIndex;
+            return lastJoin !== undefined && lastJoin > candidate.index;
+        }))).value;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await artifact.close();
+    }
+}
+/** Command/application entry: root selection uses the caller's captured environment. */
+export function gcHostLedger(options = {}) {
+    return maintainHostLedger(hostLedgerForEnv(options.env ?? process.env), options);
+}
+export async function maintainHostLedger(ledger, options = {}) {
+    const dryRun = options.dryRun === true;
+    const now = options.now ?? Date.now();
+    const records = await ledger.listEvidence({ includeReleased: true, includeExpired: true, now });
+    const groups = new Map();
+    for (const record of records) {
+        if (!isCandidate(record, now))
+            continue;
+        const index = activityIndex(record.activity);
+        if (index === undefined)
+            continue;
+        const location = await canonicalPath(record.location).catch(() => undefined);
+        if (location === undefined)
+            continue;
+        const group = groups.get(location);
+        if (group === undefined)
+            groups.set(location, [{ record, index }]);
+        else
+            group.push({ record, index });
+    }
+    let eligible = 0;
+    let retired = 0;
+    let casMisses = 0;
+    const unavailable = new Set();
+    for (const location of [...groups.keys()].sort()) {
+        const closable = await provenClosable(location, groups.get(location));
+        if (closable === undefined) {
+            unavailable.add(location);
+            continue;
+        }
+        eligible += closable.length;
+        if (dryRun)
+            continue;
+        for (const candidate of closable) {
+            if (await ledger.retireEvidenceIfUnchanged(candidate.record))
+                retired += 1;
+            else
+                casMisses += 1;
+        }
+    }
+    return { dryRun, eligible, retired, casMisses, unavailableArtifacts: [...unavailable].sort() };
+}

package/dist/mcp.d.ts

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { SquareApplicationContext } from './square-facade.js';
-export interface SquareMcpOptions extends SquareApplicationContext {
+/** The server owns its artifact connection lifetime, so callers cannot lend one. */
+export interface SquareMcpOptions extends Omit<SquareApplicationContext, 'resources'> {
 }
 export type SquareMcpServer = McpServer;
 export declare function createSquareMcpServer(options: SquareMcpOptions): SquareMcpServer;

package/dist/mcp.js

@@ -4,7 +4,7 @@ import { z } from 'zod/v4';
 import { SquareError, isSquareError } from './model.js';
 import { operationEnv } from './automatic-session.js';
 import { SQUARE_IDENTITY } from './identity.js';
-import { createSquareApplication } from './square-application.js';
+import { createSquareApplication, createSquareResourceOwner } from './square-application.js';
 const activityId = z.string().regex(/^act\/(0|[1-9][0-9]*)$/);
 const stringArray = z.array(z.string());
 const participantName = z.string().optional().describe("Participant name, same as --as. Defaults to the server's configured participant.");
@@ -44,37 +44,62 @@ function operation(app, name, args, control) {
 }
 export function createSquareMcpServer(options) {
     const baseEnv = { ...options.env };
+    const resources = createSquareResourceOwner();
+    // One explicit lifetime for this server: every tool call borrows the same connection.
+    const inFlight = new Set();
     const server = new McpServer({ name: 'square', version: SQUARE_IDENTITY.packageVersion }, {
         instructions: 'The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.',
     });
     for (const tool of TOOL_DEFINITIONS) {
-        server.registerTool(tool.name, { description: tool.description, inputSchema: tool.inputSchema }, async (args, extra) => {
-            try {
-                const { as: participant, ...operationArgs } = args;
-                const threadId = extra._meta?.threadId;
-                const opencodeSessionId = extra._meta?.['ai.opencode/sessionID'];
-                const env = typeof threadId === 'string' && threadId.trim()
-                    ? operationEnv('codex', threadId, baseEnv)
-                    : typeof opencodeSessionId === 'string' && opencodeSessionId.trim()
-                        ? operationEnv('opencode', opencodeSessionId, baseEnv)
-                        : baseEnv;
-                const app = createSquareApplication({ ...options, env, participant: participant ?? options.participant });
-                const outcome = await operation(app, tool.name, operationArgs, { signal: extra.signal });
-                const structuredContent = outcome.data;
-                return { content: [{ type: 'text', text: JSON.stringify(structuredContent) }], structuredContent };
-            }
-            catch (error) {
-                const normalized = extra.signal.aborted
-                    ? { code: 'cancelled', message: 'The MCP request was cancelled' }
-                    : isSquareError(error)
-                        ? { code: error.code, message: error.message, ...(error.facts === undefined ? {} : { facts: error.facts }) }
-                        : { code: 'internal', message: error instanceof Error ? error.message : String(error) };
-                const operation = error instanceof Error ? error.operation : undefined;
-                const failure = operation === undefined ? normalized : { ...normalized, operation };
-                return { isError: true, content: [{ type: 'text', text: JSON.stringify(failure) }], structuredContent: { error: failure } };
-            }
+        server.registerTool(tool.name, { description: tool.description, inputSchema: tool.inputSchema }, (args, extra) => {
+            const call = (async () => {
+                try {
+                    const { as: participant, ...operationArgs } = args;
+                    const threadId = extra._meta?.threadId;
+                    const opencodeSessionId = extra._meta?.['ai.opencode/sessionID'];
+                    const env = typeof threadId === 'string' && threadId.trim()
+                        ? operationEnv('codex', threadId, baseEnv)
+                        : typeof opencodeSessionId === 'string' && opencodeSessionId.trim()
+                            ? operationEnv('opencode', opencodeSessionId, baseEnv)
+                            : baseEnv;
+                    const app = createSquareApplication({ ...options, env, participant: participant ?? options.participant, resources }, { presentation: false });
+                    const outcome = await operation(app, tool.name, operationArgs, { signal: extra.signal });
+                    const structuredContent = outcome.data;
+                    return { content: [{ type: 'text', text: JSON.stringify(structuredContent) }], structuredContent };
+                }
+                catch (error) {
+                    const normalized = extra.signal.aborted
+                        ? { code: 'cancelled', message: 'The MCP request was cancelled' }
+                        : isSquareError(error)
+                            ? { code: error.code, message: error.message, ...(error.facts === undefined ? {} : { facts: error.facts }) }
+                            : { code: 'internal', message: error instanceof Error ? error.message : String(error) };
+                    const operation = error instanceof Error ? error.operation : undefined;
+                    const failure = operation === undefined ? normalized : { ...normalized, operation };
+                    return { isError: true, content: [{ type: 'text', text: JSON.stringify(failure) }], structuredContent: { error: failure } };
+                }
+            })();
+            inFlight.add(call);
+            return call.finally(() => { inFlight.delete(call); });
         });
     }
+    const close = server.close.bind(server);
+    // One idempotent shutdown for both close paths: an explicit server.close() and a
+    // transport-initiated disconnect, where the SDK protocol fires onclose by itself.
+    let draining;
+    const drain = () => draining ??= (async () => {
+        // The SDK aborts in-flight request signals before onclose/close returns; wait for
+        // those handlers to release the shared connection (their cleanup writes included).
+        await Promise.allSettled([...inFlight]);
+        await resources.close();
+    })();
+    server.close = async () => { await close(); await drain(); };
+    const priorOnclose = server.server.onclose;
+    server.server.onclose = () => {
+        // onclose is synchronous, so the disconnect path starts the drain without awaiting it;
+        // the handler's own catch keeps an unexpected close failure from crashing the process.
+        void drain().catch(() => undefined);
+        priorOnclose?.();
+    };
     return server;
 }
 export async function runSquareMcpStdio(options) {

package/dist/model.js

@@ -37,11 +37,14 @@ export function nameKey(name) {
 export function sameName(a, b) {
     return nameKey(a) === nameKey(b);
 }
+const TEXT_NAME_GRAPHEME_SOURCE = String.raw `[[\p{L}\p{N}\p{M}_\x2D]--[\p{Variation_Selector}]]`;
 /** One name grapheme: Unicode letters, digits, marks, hyphens, or underscores (no isolated variation selectors), or a complete RGI emoji. Shared by name validation and body @mention scanning. */
-export const NAME_GRAPHEME_SOURCE = String.raw `[[\p{L}\p{N}\p{M}_\x2D]--[\p{Variation_Selector}]]|\p{RGI_Emoji}`;
+export const NAME_GRAPHEME_SOURCE = String.raw `${TEXT_NAME_GRAPHEME_SOURCE}|\p{RGI_Emoji}`;
+// Ordinary Unicode names need not trigger the full RGI emoji matcher’s cold compilation.
+const TEXT_NAME_PATTERN = new RegExp(`^(?:${TEXT_NAME_GRAPHEME_SOURCE})+(?:/(?:${TEXT_NAME_GRAPHEME_SOURCE})+)*$`, 'v');
 const NAME_PATTERN = new RegExp(`^(?:${NAME_GRAPHEME_SOURCE})+(?:/(?:${NAME_GRAPHEME_SOURCE})+)*$`, 'v');
 export function validateName(name) {
-    if (!name || !NAME_PATTERN.test(name)) {
+    if (!name || (!TEXT_NAME_PATTERN.test(name) && !NAME_PATTERN.test(name))) {
         throw new SquareError('invalid_name', 'Invalid name: names must contain non-empty slash-separated segments using Unicode letters, digits, marks, hyphens, underscores, or complete RGI emoji graphemes.');
     }
 }

package/dist/open-square.d.ts

@@ -1,4 +1,4 @@
-import type { HostLedgerPort, SquareArtifactPort, WakeTransportPort } from './ports.js';
+import type { HostLedgerPort, SquareArtifactPort, SquareResourceOwner, WakeTransportPort } from './ports.js';
 import type { OperationControl } from './square-facade.js';
 /** Host-bound resource: artifact, captured environment, clock, ledger and transport. */
 export interface OpenSquare {
@@ -8,6 +8,8 @@ export interface OpenSquare {
     readonly hostLedger?: HostLedgerPort;
     readonly wakeTransport?: WakeTransportPort;
     readonly env?: NodeJS.ProcessEnv;
+    /** False when a long-lived owner lent the connection; closing this view leaves it open. */
+    readonly ownsArtifact: boolean;
 }
 export interface SquareBuildOptions {
     markdown: string;
@@ -20,7 +22,15 @@ export interface SquareBuildOptions {
     /** One caller deadline propagated into artifact busy retries. */
     signal?: AbortSignal;
 }
-export declare function openSquare(squarePath: string, options?: Pick<SquareBuildOptions, 'clock' | 'hostLedger' | 'wakeTransport' | 'env' | 'signal'>, control?: OperationControl): Promise<OpenSquare>;
+export interface SquareOpenOptions extends Pick<SquareBuildOptions, 'clock' | 'hostLedger' | 'wakeTransport' | 'env' | 'signal'> {
+    /** A caller-owned connection to reuse; this view never closes it. */
+    readonly artifact?: SquareArtifactPort;
+}
+export declare function openSquare(squarePath: string, options?: SquareOpenOptions, control?: OperationControl): Promise<OpenSquare>;
 export declare function buildSquare(squarePath: string, options: SquareBuildOptions): Promise<OpenSquare>;
 export declare function buildMemorySquare(options: SquareBuildOptions): OpenSquare;
 export declare function closeOpenSquare(square: OpenSquare): Promise<void>;
+/** Explicit-lifetime holder of one reused artifact connection. The first request
+ * binds the location; a request for any other location is refused instead of
+ * silently sharing the wrong square. The owner closes the connection once. */
+export declare function createSquareResourceOwner(): SquareResourceOwner;

package/dist/open-square.js

@@ -1,20 +1,25 @@
+import path from 'node:path';
 import { createArtifactPort, createSquare, prepareSquareBuild } from './artifact.js';
 import { InternalSquareError, SquareError } from './model.js';
 import { hostLedgerRoot } from './host-ledger-root.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 export async function openSquare(squarePath, options = {}, control) {
     const env = { ...(options.env ?? process.env) };
-    const artifact = createArtifactPort(squarePath, undefined, options.signal);
+    const borrowed = options.artifact;
+    // A borrowed connection was opened by its owner without a request signal; this
+    // request may only abort its own read, never the shared connection's lifetime.
+    const artifact = borrowed ?? createArtifactPort(squarePath, undefined, options.signal);
     try {
         await artifact.read(facts => facts.header(), control?.signal);
         return {
-            artifact, clock: options.clock ?? Date.now, location: squarePath, env,
+            artifact, clock: options.clock ?? Date.now, location: squarePath, env, ownsArtifact: borrowed === undefined,
             hostLedger: options.hostLedger ?? createHostLedgerPort({ rootPath: hostLedgerRoot(env) }),
             wakeTransport: options.wakeTransport,
         };
     }
     catch (error) {
-        await artifact.close();
+        if (borrowed === undefined)
+            await artifact.close();
         if (error instanceof InternalSquareError && error.code === 'not_found')
             throw new SquareError('unavailable', `Square is unavailable at ${squarePath}`);
         throw error;
@@ -36,8 +41,41 @@ export function buildMemorySquare(options) {
         artifact: createArtifactPort(':memory:', prepareSquareBuild(options, options.markdown)),
         clock: options.clock ?? Date.now, location: 'memory',
         hostLedger: options.hostLedger, wakeTransport: options.wakeTransport,
+        ownsArtifact: true,
     };
 }
 export function closeOpenSquare(square) {
-    return square.artifact.close();
+    // A borrowed connection belongs to its owner; only owned views close it here.
+    return square.ownsArtifact === false ? Promise.resolve() : square.artifact.close();
+}
+/** Explicit-lifetime holder of one reused artifact connection. The first request
+ * binds the location; a request for any other location is refused instead of
+ * silently sharing the wrong square. The owner closes the connection once. */
+export function createSquareResourceOwner() {
+    let held;
+    let closed = false;
+    return {
+        artifact(location) {
+            if (closed)
+                throw new SquareError('unavailable', 'Square resource owner is closed');
+            const key = path.resolve(location);
+            if (held === undefined) {
+                // No external signal: a request must never become the shared connection's lifetime.
+                held = { location: key, artifact: createArtifactPort(key) };
+            }
+            if (held.location !== key) {
+                throw new SquareError('unavailable', `Square resource owner already holds ${held.location}; it cannot also open ${key}`);
+            }
+            return held.artifact;
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            const artifact = held?.artifact;
+            held = undefined;
+            if (artifact !== undefined)
+                await artifact.close();
+        },
+    };
 }

package/dist/participant-host.js

@@ -11,8 +11,12 @@ export async function identityRouteDraft(context, participant) {
         return undefined;
     const identity = processIdentity(context.env ?? process.env);
     const provider = identity.channel === 'claude-code' ? 'claude' : identity.channel === 'opencode' ? 'opencode' : identity.channel === 'pi' ? 'pi' : identity.channel === 'paseo' ? 'paseo' : 'codex';
-    const capabilities = context.hostLedger === undefined ? { canUse: () => false } : await defaultWakeRouteCapabilities(context.hostLedger);
-    return resolvePrimaryWakeRoute({ location: context.location, participant, sessionId: identity.session, provider }, context.env ?? process.env, capabilities);
+    const boundary = { location: context.location, participant, sessionId: identity.session, provider };
+    const env = context.env ?? process.env;
+    // No adapter can add a route when the host has no candidate in the first place.
+    if (context.hostLedger === undefined || resolvePrimaryWakeRoute(boundary, env, { canUse: () => true }) === undefined)
+        return undefined;
+    return resolvePrimaryWakeRoute(boundary, env, await defaultWakeRouteCapabilities(context.hostLedger));
 }
 /** One postcommit host observation; presence and route publication fail independently. */
 export async function publishCommittedIdentity(context, participant, epoch) {

package/dist/ports.d.ts

@@ -1,5 +1,5 @@
 import type { Act, HardCap, InboxNotification, StoredAct, WakeRoute, WakeRouteKind, WatchLease } from './model.js';
-export type { ClaimResult, EvidenceClaim, EvidenceRelease, EvidenceGc, EvidenceLookup, EvidenceRecord, HostLedgerPort, PresenceKey, PresenceLookup, PresenceRecord, PresenceClaimResult, PresenceChannel, PresenceResult, } from './host-ledger.js';
+export type { ClaimResult, EvidenceClaim, EvidenceRelease, EvidenceLookup, EvidenceRecord, NativeTokenLookup, NativeTokenResult, HostLedgerPort, PresenceKey, PresenceLookup, PresenceRecord, PresenceClaimResult, PresenceChannel, PresenceResult, } from './host-ledger.js';
 import type { HostLedgerPort } from './host-ledger.js';
 export type ActivityIndex = number;
 export interface SquareHeader {
@@ -20,6 +20,11 @@ export interface ParticipantFact {
     readonly lastActiveAt?: number;
     readonly lastJoinIndex?: number;
 }
+export interface ParticipantCounts {
+    readonly known: number;
+    readonly joined: number;
+    readonly done: number;
+}
 export interface AttentionFact {
     readonly listener: string;
     readonly target: string;
@@ -98,6 +103,7 @@ export interface RouteFact {
 export interface SquareRead {
     header(): SquareHeader;
     participant(requestedName: string): ParticipantFact | undefined;
+    participantCounts(): ParticipantCounts;
     roster(): readonly ParticipantFact[];
     attention(listener: string): readonly AttentionFact[];
     incomingAttention(sender: string): readonly AttentionFact[];
@@ -159,6 +165,16 @@ export interface SquareArtifactPort {
     changed(sinceVersion: number, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
     close(): Promise<void>;
 }
+/** Explicit lifetime for an artifact connection reused by a long-lived caller.
+ * Only the connection is shared: every open still derives its own environment,
+ * clock, ledger and transport, and no request signal becomes a connection lifetime.
+ * The owner holds one location and refuses a second rather than sharing the wrong
+ * square; the caller lends the connection and never closes it. */
+export interface SquareResourceOwner {
+    /** The shared connection for a location. Never close it; the owner does. */
+    artifact(location: string): SquareArtifactPort;
+    close(): Promise<void>;
+}
 /** Capability-neutral wake transport. Unused by this Contract's activity operations. */
 export interface WakeTransportPort {
     /** Capability check that performs no external wake and writes no evidence. */

package/dist/runtime.d.ts

@@ -1,6 +1,6 @@
 import { type ActivityId } from './square-core.js';
 import { type StoredAct, type WatchLease } from './model.js';
-import type { SquareRead } from './ports.js';
+import type { ParticipantCounts, ParticipantFact, SquareRead } from './ports.js';
 export declare const WATCH_HEARTBEAT_MS: number;
 export declare const SLEEP_MS: number;
 export declare const STALE_MS: number;
@@ -13,6 +13,7 @@ export declare function nowMs(): number;
 export declare function rosterNames(facts: SquareRead): string[];
 export declare function inSquareCount(facts: SquareRead): number;
 export declare function actId(actOrIndex: StoredAct | number): ActivityId;
+export declare function terminalStatusFor(current: ParticipantFact | undefined, hardCap: number | null, counts: ParticipantCounts): 'capped' | 'quorum' | undefined;
 export declare function watchTerminalStatus(facts: SquareRead, name: string): 'capped' | 'quorum' | undefined;
 /** A continuous prefix stops at the first unseen historical audience edge after join. */
 export declare function readCursor(facts: SquareRead, name: string): number;

package/dist/runtime.js

@@ -1,5 +1,5 @@
 import { formatActivityId } from './square-core.js';
-import { SquareError, sameName } from './model.js';
+import { SquareError } from './model.js';
 function parseIntegerEnv(name, fallback) {
     const raw = process.env[name];
     if (raw === undefined)
@@ -27,14 +27,20 @@ export function nowMs() {
     return value;
 }
 export function rosterNames(facts) { return facts.roster().map((participant) => participant.name); }
-export function inSquareCount(facts) { return facts.roster().filter((participant) => participant.joined).length; }
+export function inSquareCount(facts) { return facts.participantCounts().joined; }
 export function actId(actOrIndex) { return formatActivityId(typeof actOrIndex === 'number' ? actOrIndex : actOrIndex.index); }
+export function terminalStatusFor(current, hardCap, counts) {
+    if (hardCap !== null && (current?.sayCount ?? 0) >= hardCap)
+        return 'capped';
+    const peers = counts.known - Number(current !== undefined);
+    const donePeers = counts.done - Number(current?.done === true);
+    return peers > 0 && donePeers === peers ? 'quorum' : undefined;
+}
 export function watchTerminalStatus(facts, name) {
-    const cap = facts.header().hardCap;
-    if (cap !== null && (facts.participant(name)?.sayCount ?? 0) >= cap)
+    const cap = facts.header().hardCap, current = facts.participant(name);
+    if (cap !== null && (current?.sayCount ?? 0) >= cap)
         return 'capped';
-    const peers = facts.roster().filter((participant) => !sameName(participant.name, name));
-    return peers.length > 0 && peers.every((peer) => peer.done) ? 'quorum' : undefined;
+    return terminalStatusFor(current, cap, facts.participantCounts());
 }
 /** A continuous prefix stops at the first unseen historical audience edge after join. */
 export function readCursor(facts, name) {

package/dist/sqlite-transaction.d.ts

@@ -0,0 +1,5 @@
+import type { DatabaseSync } from 'node:sqlite';
+/** Yield rather than blocking the process while another connection owns SQLite. */
+export declare function retrySqliteBusy<T>(operation: () => T, signal?: AbortSignal, retryMs?: number | (() => number)): Promise<T>;
+/** Acquisition may retry; COMMIT retries retain the callback's result and transaction. */
+export declare function inSqliteTransaction<T, V>(db: DatabaseSync, write: boolean, validate: () => V, change: (validated: V) => T, signal?: AbortSignal): Promise<T>;