@astrosheep/square 0.3.70 → 0.3.72

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Square } from './square-wiring.js';
+export { Square } from './square-application.js';
 export { createSquareApplication } from './square-application.js';
 export { SquareError } from './model.js';
 export { squareAssignedParticipantName } from './registry.js';
@@ -6,6 +6,4 @@ export { createDefaultWakeTransport } from './notifications.js';
 export { createHostLedgerPort, FileHostLedgerPort } from './host-ledger-file-adapter.js';
 export type { HostLedgerPort, PresenceRecord, EvidenceRecord } from './host-ledger.js';
 export type { PresentationSinkPort } from './ports.js';
-export type { SquareApplication, SquareApplicationContext, JoinApplicationOptions, JoinApplicationResult, ExpressApplicationOptions, ApplicationStatus, ApplicationStatusProjection, ApplicationParticipants } from './square-application.js';
-export type { ActivityId } from './square-core.js';
-export type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, HistoryQuery, OperationControl, OperationProgress, ListenerChangeResult, OpenOptions, Participant, ParticipantStatus, PerceivedActivity, SquareAtInput, SquareBuildInput, SquareSnapshot, SquareSource, } from './square-facade.js';
+export type * from './square-facade.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Square } from './square-wiring.js';
+export { Square } from './square-application.js';
 export { createSquareApplication } from './square-application.js';
 export { SquareError } from './model.js';
 export { squareAssignedParticipantName } from './registry.js';

package/dist/list.d.ts

@@ -1 +1,7 @@
-export declare function cmdListSquares(args: string[], usage: () => void): Promise<void>;
+import type { DiscoveryApplicationData, DiscoveryApplicationOptions, OpenOptions, 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. Only the application calls this private operation. */
+export declare function discoverSquares(root: string, options?: DiscoveryApplicationOptions, control?: OperationControl, openOptions?: OpenOptions): Promise<DiscoveryApplicationData>;

package/dist/list.js

@@ -1,46 +1,51 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { probeSquare } from './square-file-adapter.js';
+import { openSquare } from './open-square.js';
 import { closeOpenSquare } from './open-square.js';
 import { listPresentation } from './views.js';
-import { formatRelativeTime } from './time.js';
-import { participantIdentity, quoteShell } from './presentation.js';
-import { style } from './tty-style.js';
-const DEFAULT_LIST_DEPTH = 4;
-const MAX_LIST_DEPTH = 16;
-const DEFAULT_LIST_LIMIT = 20;
-const MAX_LIST_LIMIT = 100;
+import { SquareError } from './model.js';
+export const DEFAULT_LIST_DEPTH = 4;
+export const MAX_LIST_DEPTH = 16;
+export const DEFAULT_LIST_LIMIT = 20;
+export const MAX_LIST_LIMIT = 100;
 const LIST_DISCOVERY_BUDGET = 10_000;
-const CONTEXT_PREVIEW_LINES = 2;
-const PARTICIPANT_PREVIEW_COUNT = 3;
-const DISPLAY_CHARACTER_LIMIT = 160;
 const LIST_SKIP_DIRS = new Set(['.git', 'node_modules', 'dist']);
-async function readSquareListItem(filePath, root) {
-    let stat;
+async function readSquareListItem(filePath, root, options, control) {
+    if (!filePath.endsWith('.square'))
+        return null;
     try {
-        stat = await fs.promises.stat(filePath);
+        control?.signal?.throwIfAborted();
+        const stat = await fs.promises.stat(filePath);
+        const square = await openSquare(filePath, { ...options, env: options.env ?? {}, signal: control?.signal }, control);
+        const projection = await listPresentation(square, control).finally(() => closeOpenSquare(square));
+        return {
+            path: path.relative(root, filePath) || path.basename(filePath),
+            lastActiveAt: stat.mtimeMs,
+            context: [...projection.context].map((line) => line.trim()).filter(Boolean),
+            participants: [...projection.participants],
+            activities: projection.activities,
+        };
     }
-    catch {
+    catch (error) {
+        control?.signal?.throwIfAborted();
+        // A vanished, unreadable or undecodable candidate does not abort discovery.
         return null;
     }
-    const square = await probeSquare(filePath);
-    if (square === undefined)
-        return null;
-    const projection = await listPresentation(square).finally(() => closeOpenSquare(square));
-    const relative = path.relative(root, filePath) || path.basename(filePath);
-    return {
-        path: relative,
-        lastActiveAt: stat.mtimeMs,
-        context: [...projection.context].map((line) => line.trim()).filter(Boolean),
-        participants: [...projection.participants],
-        activities: projection.activities,
-    };
 }
-async function collectSquareList(root, maxDepth) {
+/** Bounded deterministic discovery. Only the application calls this private operation. */
+export async function discoverSquares(root, options = {}, control, openOptions = {}) {
+    const depth = options.depth ?? DEFAULT_LIST_DEPTH;
+    const limit = options.limit ?? DEFAULT_LIST_LIMIT;
+    if (!Number.isSafeInteger(depth) || depth < 0 || depth > MAX_LIST_DEPTH
+        || !Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIST_LIMIT
+        || (options.after !== undefined && (options.after.length === 0 || path.isAbsolute(options.after)))) {
+        throw new SquareError('invalid_args', 'Invalid discovery depth, limit or relative cursor');
+    }
     const items = [];
     let examined = 0;
     let stopped = false;
-    async function walk(dir, depth) {
+    async function walk(dir, level) {
+        control?.signal?.throwIfAborted();
         if (stopped)
             return;
         let entries;
@@ -48,110 +53,32 @@ async function collectSquareList(root, maxDepth) {
             entries = await fs.promises.readdir(dir, { withFileTypes: true });
         }
         catch {
-            // Directory vanished or became unreadable mid-walk — skip it, don't abort the scan.
+            control?.signal?.throwIfAborted();
             return;
         }
         entries.sort((left, right) => left.name.localeCompare(right.name));
         for (const entry of entries) {
+            control?.signal?.throwIfAborted();
             if (stopped)
                 return;
-            examined += 1;
-            if (examined === LIST_DISCOVERY_BUDGET)
+            if (++examined === LIST_DISCOVERY_BUDGET)
                 stopped = true;
             const fullPath = path.join(dir, entry.name);
             if (entry.isDirectory()) {
-                if (!stopped && depth < maxDepth && !LIST_SKIP_DIRS.has(entry.name))
-                    await walk(fullPath, depth + 1);
-                continue;
+                if (!stopped && level < depth && !LIST_SKIP_DIRS.has(entry.name))
+                    await walk(fullPath, level + 1);
             }
-            if (!entry.isFile())
-                continue;
-            const item = await readSquareListItem(fullPath, root);
-            if (item)
-                items.push(item);
-        }
-    }
-    await walk(root, 0);
-    return { items: items.sort((a, b) => a.path.localeCompare(b.path)), stopped };
-}
-function characterPreview(value) {
-    const characters = Array.from(value);
-    return characters.length <= DISPLAY_CHARACTER_LIMIT ? value : `${characters.slice(0, DISPLAY_CHARACTER_LIMIT - 1).join('')}…`;
-}
-function renderSquareList(items, stopped, depth, limit, after) {
-    const page = after === undefined ? items : items.filter((item) => item.path.localeCompare(after) > 0);
-    const shownItems = page.slice(0, limit);
-    if (items.length === 0) {
-        return [`(no squares found)`, ...(stopped ? [style('dim', `○ the walk stopped early — deeper squares may still be hiding`)] : [])].join('\n') + '\n';
-    }
-    const now = Date.now();
-    const lines = ['squares'];
-    for (const item of shownItems) {
-        const glyph = item.activities > 0 ? '●' : style('dim', '○');
-        lines.push(`${glyph} ${characterPreview(item.path)}${style('dim', ` · ${formatRelativeTime(item.lastActiveAt, now)} · ${item.participants.length} in the square · ${item.activities} ${item.activities === 1 ? 'activity' : 'activities'}`)}`);
-        const shownContext = item.context.slice(0, CONTEXT_PREVIEW_LINES);
-        if (shownContext.length === 0) {
-            lines.push(`  ${style('dim', 'context')} · (none)`);
-        }
-        else {
-            shownContext.forEach((line, index) => lines.push(`  ${index === 0 ? style('dim', 'context') : '       '} · ${characterPreview(line)}`));
-            const hiddenContext = item.context.length - shownContext.length;
-            if (hiddenContext > 0)
-                lines.push(style('dim', `          · … ${hiddenContext} more ${hiddenContext === 1 ? 'line' : 'lines'}`));
-        }
-        const shownParticipants = item.participants.slice(0, PARTICIPANT_PREVIEW_COUNT);
-        const hiddenParticipants = item.participants.length - shownParticipants.length;
-        const participantNames = shownParticipants.length === 0 ? 'nobody' : shownParticipants.map((participant) => participantIdentity(characterPreview(participant))).join(' · ');
-        lines.push(`  ${style('dim', 'participants')} · ${participantNames}${hiddenParticipants > 0 ? style('dim', ` · … ${hiddenParticipants} more`) : ''}`);
-    }
-    const hiddenItems = page.length - shownItems.length;
-    if (hiddenItems > 0) {
-        const cursor = shownItems.at(-1)?.path;
-        lines.push(style('dim', stopped ? '  … more squares' : `  … ${hiddenItems} more ${hiddenItems === 1 ? 'square' : 'squares'}`));
-        if (cursor !== undefined)
-            lines.push(`square list --depth ${depth} --limit ${limit} --after ${quoteShell(cursor)}`);
-    }
-    if (stopped)
-        lines.push(style('dim', `○ the walk stopped early — deeper squares may still be hiding`));
-    return lines.join('\n') + '\n';
-}
-function parseListOptions(args, usage) {
-    let depth = DEFAULT_LIST_DEPTH;
-    let limit = DEFAULT_LIST_LIMIT;
-    let after;
-    for (let index = 0; index < args.length; index += 2) {
-        const option = args[index];
-        const value = args[index + 1];
-        if (value === undefined || (option !== '--depth' && option !== '--limit' && option !== '--after')) {
-            usage();
-            return { depth, limit };
-        }
-        if (option === '--after') {
-            if (after !== undefined || value.length === 0 || path.isAbsolute(value)) {
-                usage();
-                return { depth, limit };
+            else if (entry.isFile()) {
+                const item = await readSquareListItem(fullPath, root, openOptions, control);
+                if (item !== null)
+                    items.push(item);
             }
-            after = value;
-            continue;
         }
-        if (!/^\d+$/.test(value)) {
-            usage();
-            return { depth, limit };
-        }
-        const parsed = Number(value);
-        if (!Number.isSafeInteger(parsed) || (option === '--depth' ? parsed > MAX_LIST_DEPTH : parsed === 0 || parsed > MAX_LIST_LIMIT)) {
-            usage();
-            return { depth, limit };
-        }
-        if (option === '--depth')
-            depth = parsed;
-        else
-            limit = parsed;
     }
-    return { depth, limit, after };
-}
-export async function cmdListSquares(args, usage) {
-    const options = parseListOptions(args, usage);
-    const discovery = await collectSquareList(process.cwd(), options.depth);
-    process.stdout.write(renderSquareList(discovery.items, discovery.stopped, options.depth, options.limit, options.after));
+    await walk(root, 0);
+    const page = items.sort((a, b) => a.path.localeCompare(b.path))
+        .filter((item) => options.after === undefined || item.path.localeCompare(options.after) > 0);
+    const selected = page.slice(0, limit);
+    const remaining = page.length - selected.length;
+    return { items: selected, total: items.length, stopped, remaining, ...(remaining > 0 ? { next: selected.at(-1).path } : {}) };
 }

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type SquareApplicationContext } from './square-application.js';
+import type { SquareApplicationContext } from './square-facade.js';
 export interface SquareMcpOptions extends SquareApplicationContext {
 }
 export type SquareMcpServer = McpServer;

package/dist/mcp.js

@@ -5,7 +5,6 @@ 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 { toPublicActivity } from './views.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.");
@@ -23,36 +22,6 @@ const TOOL_DEFINITIONS = [
     { name: 'status', description: 'Read the public status of the square.', inputSchema: z.object({}).strict() },
     { name: 'participants', description: 'List participants standing in or done with the square.', inputSchema: z.object({}).strict() },
 ];
-function isObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
-function publicActivity(activity) { return { ...activity }; }
-function publicResult(name, value) {
-    if (name === 'status') {
-        const result = value;
-        const state = result.status;
-        const { latestAct, participants, ...rest } = state;
-        return {
-            hardCap: rest.hardCap,
-            ...(rest.throttlePerMinute === undefined ? {} : { throttlePerMinute: rest.throttlePerMinute }),
-            activeCount: rest.activeCount,
-            doneCount: rest.doneCount,
-            hold: rest.holdActive ? { by: rest.holdActor, ...(rest.holdReason === undefined ? {} : { reason: rest.holdReason }), ...(rest.holdAt === undefined ? {} : { at: rest.holdAt }) } : null,
-            participants: participants.filter((participant) => participant.state !== 'not joined').map((participant) => ({ name: participant.name, state: participant.state, presence: participant.presence, activityCount: participant.activityCount, ...(participant.lastActiveAt === undefined ? {} : { lastActiveAt: participant.lastActiveAt }), unreadActivityCount: participant.unreadActivityCount, pendingMentionCount: participant.pendingMentionCount, listening: participant.listening })),
-            ...(latestAct === undefined ? {} : { latestActivity: publicActivity(toPublicActivity(latestAct)) }),
-            now: rest.now,
-        };
-    }
-    if (name === 'express' || name === 'hold' || name === 'resume' || name === 'done') {
-        const result = value;
-        return { ...(result.activity === undefined ? {} : { activity: result.activity === null ? null : publicActivity(result.activity) }), ...(result.waited === undefined ? {} : { waited: result.waited }), ...(result.replyAuthorNotHere === undefined ? {} : { replyAuthorNotHere: result.replyAuthorNotHere }) };
-    }
-    if (name === 'history')
-        return { activities: value };
-    if (name === 'participants')
-        return { participants: value };
-    if (name === 'listening')
-        return { listening: value };
-    return value;
-}
 function operation(app, name, args, control) {
     switch (name) {
         case 'join': return app.join({ takeover: args.takeover }, control);
@@ -68,8 +37,8 @@ function operation(app, name, args, control) {
         case 'hold': return app.hold(args.reason, control);
         case 'resume': return app.resume(control);
         case 'done': return app.done(undefined, control);
-        case 'status': return app.status();
-        case 'participants': return app.participants();
+        case 'status': return app.status(undefined, control);
+        case 'participants': return app.participants(control);
         default: throw new SquareError('invalid_args', `Unknown tool: ${name}`);
     }
 }
@@ -90,9 +59,8 @@ export function createSquareMcpServer(options) {
                         ? operationEnv('opencode', opencodeSessionId, baseEnv)
                         : baseEnv;
                 const app = createSquareApplication({ ...options, env, participant: participant ?? options.participant });
-                const value = await operation(app, tool.name, operationArgs, { signal: extra.signal });
-                const projected = publicResult(tool.name, value);
-                const structuredContent = isObject(projected) ? projected : { result: projected };
+                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) {
@@ -101,7 +69,9 @@ export function createSquareMcpServer(options) {
                     : isSquareError(error)
                         ? { code: error.code, message: error.message, ...(error.facts === undefined ? {} : { facts: error.facts }) }
                         : { code: 'internal', message: error instanceof Error ? error.message : String(error) };
-                return { isError: true, content: [{ type: 'text', text: JSON.stringify(normalized) }], structuredContent: { error: normalized } };
+                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 } };
             }
         });
     }

package/dist/model.d.ts

@@ -15,8 +15,6 @@ export interface WakeRoute {
     address: Record<string, string>;
     updatedAt: number;
 }
-export interface ReceiverRoute extends WakeRoute {
-}
 export type SquareErrorCode = 'invalid_name' | 'invalid_args' | 'unknown_participant' | 'not_joined' | 'already_joined' | 'already_done' | 'held' | 'capped' | 'throttled' | 'bell_quota' | 'behind' | 'io' | 'unavailable';
 export type InternalSquareErrorCode = SquareErrorCode | 'not_found' | 'cap_reached' | 'conflict' | 'pending_peer';
 export interface SquareErrorFacts {
@@ -24,9 +22,11 @@ export interface SquareErrorFacts {
     activityUnsent?: true;
     /** Why a name could not be resolved: never in the roster, no longer standing in it, a bell
      * colliding with a mention, an @name that matches nobody, or an activity catch cannot address. */
-    reason?: 'never_joined' | 'not_standing' | 'bell_mention_conflict' | 'unmatched_mention' | 'not_addressed';
+    reason?: 'never_joined' | 'not_standing' | 'bell_mention_conflict' | 'unmatched_mention' | 'not_addressed' | 'migration_required' | 'explicit_reach_required' | 'invalid_reply' | 'invalid_done_body';
     /** The activity id a `catch --id` refusal named. */
     activityId?: string;
+    /** Requested recipient spellings, without parsing presentation copy. */
+    targets?: readonly string[];
     /** Whether the artifact holds that activity at all; an unknown id needs an ordinary page. */
     activityExists?: boolean;
     pending?: number;
@@ -37,6 +37,7 @@ export interface SquareErrorFacts {
 declare class SquareErrorBase<Code extends string> extends Error {
     code: Code;
     facts?: SquareErrorFacts | undefined;
+    operation?: import('./square-facade.js').ApplicationFailureDetail;
     constructor(code: Code, message: string, facts?: SquareErrorFacts | undefined);
 }
 export declare class SquareError extends SquareErrorBase<SquareErrorCode> {
@@ -55,7 +56,6 @@ export type StoredAct = Act & {
     index: number;
     at: number;
 };
-export type StoredActHead = StoredAct extends infer T ? T extends StoredAct ? Omit<T, 'body' | 'through' | 'index'> : never : never;
 export type ObservationState = 'seen';
 export interface ActivityObservation {
     state: ObservationState;
@@ -85,40 +85,6 @@ export interface InboxMembership {
     notifications: InboxNotification[];
     catchLease?: WatchLease;
 }
-export interface SquareRuntimeState {
-    nextActIndex: number;
-    observations: Record<string, Record<string, ActivityObservation>>;
-    leases: Record<string, WatchLease>;
-}
-export interface SquareState {
-    hardCap: HardCap;
-    throttlePerMinute?: number;
-    preamble: string[];
-    warmup: string[];
-    acts: StoredAct[];
-    routes?: ReceiverRoute[];
-    runtime: SquareRuntimeState;
-}
-export interface ActivitiesOptions {
-    lastN?: number | null;
-    participants?: string[];
-    /** Exclusive lower bound on act.at (ms). Alias of --since. */
-    after?: number;
-    /** Exclusive lower bound on stable act index (--after act/<index>). */
-    afterIndex?: number;
-    /** Exclusive upper bound on stable act index (--before act/<index>). */
-    beforeIndex?: number;
-    /** Center act indexes for context windows (--at). */
-    atIndexes?: number[];
-    beforeContext?: number;
-    afterContext?: number;
-    mention?: string;
-    grep?: string;
-    fixed?: string;
-    order?: 'asc' | 'desc';
-    format?: string[];
-    json?: boolean;
-}
 export interface WatchOptions {
     id?: ActivityId;
     participants?: string[];
@@ -134,16 +100,10 @@ export type PublicAct = Extract<StoredAct, {
 export type RoomChangeAct = Extract<StoredAct, {
     kind: 'join' | 'done' | 'hold' | 'resume' | 'listen' | 'ignore';
 }>;
-export interface HoldState {
-    active: boolean;
-    at?: number;
-    reason?: string;
-}
 export declare function formatHardCap(hardCap: HardCap): string;
 export declare function parseParticipantList(value: string): string[];
 export declare function nameKey(name: string): string;
 export declare function sameName(a: string, b: string): boolean;
-export declare function findParticipantName(participants: string[], name: string): string | undefined;
 /** 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 declare const NAME_GRAPHEME_SOURCE: string;
 export declare function validateName(name: string): void;

package/dist/model.js

@@ -7,6 +7,7 @@ export function isWakeRouteKind(value) {
 class SquareErrorBase extends Error {
     code;
     facts;
+    operation;
     constructor(code, message, facts) {
         super(message);
         this.code = code;
@@ -36,9 +37,6 @@ export function nameKey(name) {
 export function sameName(a, b) {
     return nameKey(a) === nameKey(b);
 }
-export function findParticipantName(participants, name) {
-    return participants.find((participant) => sameName(participant, name));
-}
 /** 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}`;
 const NAME_PATTERN = new RegExp(`^(?:${NAME_GRAPHEME_SOURCE})+(?:/(?:${NAME_GRAPHEME_SOURCE})+)*$`, 'v');

package/dist/notifications.d.ts

@@ -8,7 +8,7 @@ interface ProcessNotificationOptions {
     env?: NodeJS.ProcessEnv;
     now?: () => number;
 }
-export declare function defaultWakeAdapters(): Promise<WakeAdapter[]>;
+export declare function defaultWakeAdapters(env?: NodeJS.ProcessEnv): Promise<WakeAdapter[]>;
 export declare function createDefaultWakeTransport(hostLedger: import('./host-ledger.js').HostLedgerPort, clock: () => number, env?: NodeJS.ProcessEnv, suppliedAdapters?: readonly WakeAdapter[]): Promise<WakeTransportPort>;
 export declare function createWakeTransport(adapters: readonly WakeAdapter[], hostLedger: import('./host-ledger.js').HostLedgerPort, clock: () => number, nativePorts?: Readonly<Partial<Record<import('./model.js').WakeRouteKind, WakeTransportPort>>>): WakeTransportPort;
 export declare function processActNotificationsOnce(squarePath: string, actIndex: number, opts?: ProcessNotificationOptions): Promise<import("./ports.js").DeliveryResult>;

package/dist/notifications.js

@@ -3,10 +3,12 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { SquareError } from './model.js';
 import { displayAttentionPath } from './attention-presentation.js';
-import { openSquare } from './square-file-adapter.js';
+import { openSquare } from './open-square.js';
 import { closeOpenSquare } from './open-square.js';
 import { deliverPending, sweepPending } from './delivery-operations.js';
-import { projectWakeEvidenceFromState } from './square-projections.js';
+import { projectWakeEvidence } from './wake-eligibility.js';
+import { pendingHead } from './delivery.js';
+import { parseActivityId } from './square-core.js';
 import { canonicalPath } from './canonical-path.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 export const PRIVILEGED_HOOK_BUDGET_MS = 3000;
@@ -17,11 +19,11 @@ export function wakeGraceMs(env = process.env) {
     }
     return value;
 }
-export async function defaultWakeAdapters() {
+export async function defaultWakeAdapters(env = process.env) {
     const adapters = [];
     try {
         const { CodexQueueAdapter } = await import('./codex-queue.js');
-        adapters.push(new CodexQueueAdapter());
+        adapters.push(new CodexQueueAdapter({ env }));
     }
     catch {
         // Codex is unavailable only when this build omits its local adapter.
@@ -36,7 +38,7 @@ export async function defaultWakeAdapters() {
     return adapters;
 }
 export async function createDefaultWakeTransport(hostLedger, clock, env = process.env, suppliedAdapters) {
-    const adapters = suppliedAdapters ?? await defaultWakeAdapters();
+    const adapters = suppliedAdapters ?? await defaultWakeAdapters(env);
     const { createClaudeWakeTransport } = await import('./claude-delivery.js');
     return createWakeTransport(suppliedAdapters === undefined && env.SQUARE_DISABLE_PASEO_WAKE === '1' ? adapters.filter((adapter) => adapter.kind !== 'paseo') : adapters, hostLedger, clock, { 'claude-native': createClaudeWakeTransport(hostLedger, env) });
 }
@@ -45,8 +47,12 @@ async function observeWakeRequest(request, hostLedger, now) {
     try {
         const location = await canonicalPath(request.location);
         square = await openSquare(location, { hostLedger });
-        const { state } = await square.artifact.read();
-        const eligibility = await projectWakeEvidenceFromState({ state, hostLedger, location, now });
+        const { value: facts } = await square.artifact.read((facts) => {
+            const index = parseActivityId(request.activity);
+            const head = index === undefined ? undefined : pendingHead(facts, request.participant, index);
+            return { routes: facts.routes(), pending: head === undefined ? [] : [head] };
+        });
+        const eligibility = await projectWakeEvidence({ ...facts, hostLedger, location, now });
         return { ...eligibility.currentness({ ...request, location }), observationAvailable: true };
     }
     catch {

package/dist/open-square.d.ts

@@ -1,5 +1,6 @@
 import type { HostLedgerPort, SquareArtifactPort, WakeTransportPort } from './ports.js';
-/** Private binding assembled by storage and consumed by the four concerns. */
+import type { OperationControl } from './square-facade.js';
+/** Host-bound resource: artifact, captured environment, clock, ledger and transport. */
 export interface OpenSquare {
     readonly artifact: SquareArtifactPort;
     readonly clock: () => number;
@@ -8,5 +9,18 @@ export interface OpenSquare {
     readonly wakeTransport?: WakeTransportPort;
     readonly env?: NodeJS.ProcessEnv;
 }
-/** Package-private lifecycle boundary for bound squares. */
+export interface SquareBuildOptions {
+    markdown: string;
+    hardCap?: number | null;
+    throttlePerMinute?: number;
+    clock?: () => number;
+    hostLedger?: HostLedgerPort;
+    wakeTransport?: WakeTransportPort;
+    env?: NodeJS.ProcessEnv;
+    /** 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 declare function buildSquare(squarePath: string, options: SquareBuildOptions): Promise<OpenSquare>;
+export declare function buildMemorySquare(options: SquareBuildOptions): OpenSquare;
 export declare function closeOpenSquare(square: OpenSquare): Promise<void>;

package/dist/open-square.js

@@ -1,4 +1,43 @@
-/** Package-private lifecycle boundary for bound squares. */
+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);
+    try {
+        await artifact.read(facts => facts.header(), control?.signal);
+        return {
+            artifact, clock: options.clock ?? Date.now, location: squarePath, env,
+            hostLedger: options.hostLedger ?? createHostLedgerPort({ rootPath: hostLedgerRoot(env) }),
+            wakeTransport: options.wakeTransport,
+        };
+    }
+    catch (error) {
+        await artifact.close();
+        if (error instanceof InternalSquareError && error.code === 'not_found')
+            throw new SquareError('unavailable', `Square is unavailable at ${squarePath}`);
+        throw error;
+    }
+}
+export async function buildSquare(squarePath, options) {
+    try {
+        await createSquare(squarePath, { ...options, force: false }, options.markdown, options.signal);
+    }
+    catch (error) {
+        if (error instanceof InternalSquareError && error.code === 'conflict')
+            throw new SquareError('io', `Cannot build over an existing square at ${squarePath}`);
+        throw error;
+    }
+    return openSquare(squarePath, { ...options, signal: undefined });
+}
+export function buildMemorySquare(options) {
+    return {
+        artifact: createArtifactPort(':memory:', prepareSquareBuild(options, options.markdown)),
+        clock: options.clock ?? Date.now, location: 'memory',
+        hostLedger: options.hostLedger, wakeTransport: options.wakeTransport,
+    };
+}
 export function closeOpenSquare(square) {
     return square.artifact.close();
 }

package/dist/packages/agent-delivery/src/claude.d.ts

@@ -1,14 +1,5 @@
-import type { ClaudeDeliveryResult, ClaudeSendTextOptions, ClaudeTarget } from './types.js';
-export interface ClaudeConnectExistingOptions {
-    readonly harness: 'claude';
-    readonly sessionId: string;
-    readonly endpoint: string;
-    readonly token?: string;
-    readonly claudeHome?: string;
-    readonly timeoutMs?: number;
-    readonly signal?: AbortSignal;
-}
+import type { ClaudeConnectOptions, ClaudeDeliveryResult, ClaudeSendTextOptions, ClaudeTarget } from './types.js';
 /** Resolve an explicitly identified existing Claude native inbox; never discovers or starts one. */
-export declare function connectExisting(options: ClaudeConnectExistingOptions): Promise<ClaudeTarget>;
+export declare function connectExisting(options: ClaudeConnectOptions): Promise<ClaudeTarget>;
 /** Write once to Claude's next native boundary; local write is never native admission. */
 export declare function sendText(target: ClaudeTarget, text: string, options?: ClaudeSendTextOptions): Promise<ClaudeDeliveryResult>;

package/dist/packages/agent-delivery/src/index.d.ts

@@ -1,4 +1,6 @@
 import { DeliveryError } from './errors.js';
+import type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions } from './types.js';
+export type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions } from './types.js';
 export interface SendOptions {
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
@@ -16,48 +18,6 @@ export interface Steerable<O = SendOptions> {
 export interface Queueable<O = SendOptions> {
     queue(text: string, options?: O): Promise<Receipt>;
 }
-export interface OpenCodeConnectOptions {
-    readonly harness: 'opencode';
-    readonly sessionId: string;
-    readonly endpoint?: {
-        readonly url: string;
-        readonly auth?: {
-            readonly type: 'basic';
-            readonly username: string;
-            readonly password: string;
-        };
-    };
-    readonly registrationFile?: string;
-    readonly timeoutMs?: number;
-    readonly signal?: AbortSignal;
-}
-export interface ClaudeConnectOptions {
-    readonly harness: 'claude';
-    readonly sessionId: string;
-    readonly endpoint: string;
-    readonly token?: string;
-    readonly claudeHome?: string;
-    readonly timeoutMs?: number;
-    readonly signal?: AbortSignal;
-}
-export interface PiConnectOptions {
-    readonly harness: 'pi';
-    readonly sessionId: string;
-    readonly endpoint: string;
-    readonly timeoutMs?: number;
-    readonly signal?: AbortSignal;
-}
-export interface PaseoConnectOptions {
-    readonly harness: 'paseo';
-    readonly agentId: string;
-    readonly endpoint?: string;
-    readonly password?: string;
-    readonly authHeader?: string;
-    readonly localCredential?: string;
-    readonly paseoHome?: string;
-    readonly timeoutMs?: number;
-    readonly signal?: AbortSignal;
-}
 export type OpenCodeAgent = Steerable<KeyedSendOptions> & Queueable<KeyedSendOptions> & {
     readonly harness: 'opencode';
     readonly sessionId: string;