@astrosheep/square 0.3.31 → 0.3.33

package/dist/notifications.js

@@ -1,5 +1,6 @@
 import { setTimeout as sleep } from 'node:timers/promises';
 import path from 'node:path';
+import fs from 'node:fs';
 import { planActNotifications, } from './delivery.js';
 import { SquareError } from './model.js';
 import { SLEEP_MS, matchesMentionTarget } from './runtime.js';
@@ -13,6 +14,7 @@ import { projectPresentationEvidence } from './square-projections.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 export { planActNotifications, matchesMentionTarget };
 export { notificationMessageId } from './delivery.js';
+export const PRIVILEGED_HOOK_BUDGET_MS = 3000;
 export function wakeGraceMs(env = process.env) {
     const value = Number.parseInt(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? '5000', 10);
     if (!Number.isFinite(value) || value <= 0) {
@@ -77,7 +79,7 @@ export async function waitForDeliveredNotification(squarePath, name, ref, opts =
     }
     return false;
 }
-async function defaultWakeAdapters() {
+export async function defaultWakeAdapters() {
     const adapters = [];
     try {
         const { CodexQueueAdapter } = await import('./codex-queue.js');
@@ -95,20 +97,38 @@ async function defaultWakeAdapters() {
     }
     return adapters;
 }
-function createWakeTransport(adapters, hostLedger, clock) {
+export async function createDefaultWakeTransport(hostLedger, clock, env = process.env) {
+    const adapters = await defaultWakeAdapters();
+    return createWakeTransport(env.SQUARE_DISABLE_PASEO_WAKE === '1' ? adapters.filter((adapter) => adapter.kind !== 'paseo') : adapters, hostLedger, clock);
+}
+export function createWakeTransport(adapters, hostLedger, clock) {
     return {
-        attempt: async (request, _timeoutMs) => {
+        probe: async (route) => {
+            const adapter = adapters.find((candidate) => candidate.kind === route.kind);
+            if (adapter === undefined)
+                return { outcome: 'not-capable', diagnostic: `no adapter for ${route.kind}` };
+            const probe = adapter.probe;
+            if (probe === undefined)
+                return true;
+            try {
+                return await probe.call(adapter, route.address);
+            }
+            catch (error) {
+                return { outcome: 'not-capable', diagnostic: error instanceof Error ? error.message : String(error) };
+            }
+        },
+        attempt: async (request, timeoutMs) => {
             const adapter = adapters.find((candidate) => candidate.kind === request.route.kind);
             if (adapter === undefined)
-                return { outcome: 'failed', message: 'wake adapter unavailable' };
+                return { outcome: 'not-capable', diagnostic: `no adapter for ${request.route.kind}` };
             try {
-                const result = await adapter.dispatch(request.route.address, renderWakePayload(request), async () => true);
+                const result = await adapter.dispatch(request.route.address, renderWakePayload(request), async () => true, timeoutMs);
                 if (result.outcome === 'accepted')
                     return { outcome: 'accepted' };
                 if (result.outcome === 'failed')
                     return { outcome: 'failed', message: result.message };
                 if (result.outcome === 'unavailable')
-                    return { outcome: 'failed', message: result.message, unavailable: true };
+                    return { outcome: 'failed', message: result.message, unavailable: true, ...(result.retainRoute === true ? { retainRoute: true } : {}), ...(result.routeStale === true ? { routeStale: true } : {}) };
                 if (result.outcome === 'unknown')
                     return { outcome: 'unknown', diagnostic: result.message };
                 return { outcome: 'unknown', diagnostic: 'wake dispatch cancelled' };
@@ -117,15 +137,6 @@ function createWakeTransport(adapters, hostLedger, clock) {
                 return { outcome: 'unknown', diagnostic: error instanceof Error ? error.message : String(error) };
             }
         },
-        invalidate: async (request) => {
-            await hostLedger.ensurePresence({
-                location: request.route.location,
-                participant: request.route.participant,
-                session: request.route.sessionId,
-                channel: request.route.channel,
-                updatedAt: clock(),
-            }, 'user');
-        },
     };
 }
 export async function processActNotificationsOnce(squarePath, actIndex, opts = {}) {
@@ -140,12 +151,69 @@ export async function processActNotificationsOnce(squarePath, actIndex, opts = {
     try {
         const adapters = opts.adapters ?? await defaultWakeAdapters();
         const transport = createWakeTransport(adapters, hostLedger, now);
-        return await deliverPending({ artifact: square.artifact, hostLedger, transport, location: squarePath, activity: actIndex, timeoutMs: Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000), now: now() });
+        try {
+            return await deliverPending({ artifact: square.artifact, hostLedger, transport, location: squarePath, activity: actIndex, timeoutMs: Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000), now: now() });
+        }
+        catch {
+            return { attempted: 0, accepted: 0, failed: 0, unknown: 0, notCapable: 1 };
+        }
     }
     finally {
         await closeOpenSquare(square);
     }
 }
+/** Privileged hook fallback: sweep indexed squares plus the current cwd's local squares within one boundary budget. */
+export async function sweepPrivilegedPending(cwd, env = process.env, suppliedAdapters, deadline = Date.now() + PRIVILEGED_HOOK_BUDGET_MS) {
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+    if (remainingMs() === 0)
+        return;
+    const root = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
+    const hostLedger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? root, localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? root, readableScopes: ['user'], writableScope: 'user' });
+    let indexed = [];
+    try {
+        indexed = await hostLedger.listPresence({ scopes: ['user'], now: Date.now() });
+    }
+    catch { /* capability is best effort */ }
+    const paths = new Set(indexed.map((binding) => binding.location));
+    try {
+        for (const entry of await fs.promises.readdir(path.join(cwd, '.square'))) {
+            if (entry.endsWith('.square'))
+                paths.add(path.join(cwd, '.square', entry));
+        }
+    }
+    catch { /* no local square directory */ }
+    if (remainingMs() === 0)
+        return;
+    const adapters = suppliedAdapters ?? await defaultWakeAdapters();
+    for (const squarePath of paths) {
+        if (remainingMs() === 0)
+            break;
+        try {
+            const square = await openSquare(squarePath, { hostLedger, env });
+            try {
+                await hostLedger.reconcileBinding({ artifact: square.artifact, scopes: ['user'], now: Date.now() }).catch(() => undefined);
+                if (remainingMs() === 0)
+                    break;
+                const limit = Number.parseInt(env.SQUARE_NOTIFY_SWEEP_LIMIT ?? '8', 10);
+                const graceMs = 0;
+                const selected = await sweepPending({ artifact: square.artifact, hostLedger, location: squarePath, now: Date.now(), graceMs, limit: Number.isFinite(limit) && limit > 0 ? limit : 8 }).catch(() => []);
+                const transport = createWakeTransport(adapters, hostLedger, Date.now);
+                for (const actIndex of selected) {
+                    const remaining = remainingMs();
+                    if (remaining === 0)
+                        break;
+                    const configured = Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000);
+                    const timeoutMs = Math.max(1, Math.min(Number.isFinite(configured) && configured > 0 ? configured : 5000, remaining));
+                    await deliverPending({ artifact: square.artifact, hostLedger, transport, location: squarePath, activity: actIndex, timeoutMs, now: Date.now() }).catch(() => undefined);
+                }
+            }
+            finally {
+                await closeOpenSquare(square);
+            }
+        }
+        catch { /* stale index entries are ignored by the hook */ }
+    }
+}
 /** Select sweep candidates from one frozen snapshot and one delivery replay. */
 export async function pendingNotificationSweepFromState(squarePath, state, now, env, limit, deriveDelivery) {
     const ledger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER, writableScope: 'user', readableScopes: ['user'] });

package/dist/open-square.d.ts

@@ -1,10 +1,11 @@
-import type { HostLedgerPort, SquareArtifactPort } from './ports.js';
+import type { HostLedgerPort, SquareArtifactPort, WakeTransportPort } from './ports.js';
 /** Private binding assembled by storage and consumed by the four concerns. */
 export interface OpenSquare {
     readonly artifact: SquareArtifactPort;
     readonly clock: () => number;
     readonly location: string;
     readonly hostLedger?: HostLedgerPort;
+    readonly wakeTransport?: WakeTransportPort;
     readonly env?: NodeJS.ProcessEnv;
 }
 /** Package-private lifecycle boundary for bound squares. */

package/dist/paseo-delivery.d.ts

@@ -10,5 +10,5 @@ export declare class PaseoAdapter implements WakeAdapter {
     private readonly opts;
     readonly kind: "paseo";
     constructor(opts?: PaseoAdapterOptions);
-    dispatch(address: Readonly<Record<string, string>>, payload: string, beforeSend: () => Promise<boolean>): Promise<WakeDispatchResult>;
+    dispatch(address: Readonly<Record<string, string>>, payload: string, beforeSend: () => Promise<boolean>, timeoutMs?: number): Promise<WakeDispatchResult>;
 }

package/dist/paseo-delivery.js

@@ -30,17 +30,29 @@ export class PaseoAdapter {
     constructor(opts = {}) {
         this.opts = opts;
     }
-    async dispatch(address, payload, beforeSend) {
+    async dispatch(address, payload, beforeSend, timeoutMs = 5000) {
+        const deadline = Date.now() + timeoutMs;
+        const remainingMs = () => Math.max(0, deadline - Date.now());
+        const budgetUnavailable = () => ({
+            outcome: 'unavailable',
+            signature: 'dispatch_budget_exhausted',
+            message: 'The wake dispatch budget elapsed before Paseo accepted the wake.',
+            retainRoute: true,
+        });
         const agentId = address.agentId?.trim();
         if (!agentId) {
             return {
                 outcome: 'unavailable',
                 signature: 'invalid_address',
                 message: 'Paseo route has no agent id.',
+                routeStale: true,
                 diagnostic: diagnostic('selection', address, 'invalid_address'),
             };
         }
-        const discovery = (this.opts.discover ?? discoverPaseoAgents)();
+        let remaining = remainingMs();
+        if (remaining === 0)
+            return budgetUnavailable();
+        const discovery = (this.opts.discover ?? discoverPaseoAgents)(remaining);
         if (discovery.error && discovery.agents.length === 0) {
             return {
                 outcome: 'unavailable',
@@ -58,9 +70,13 @@ export class PaseoAdapter {
                 message: agent === undefined ? 'The registered Paseo agent was not found.' : 'The registered Paseo agent is not idle.',
                 diagnostic: diagnostic('selection', address, agent === undefined ? 'not_found' : 'not_idle'),
                 ...(agent === undefined ? {} : { retainRoute: true }),
+                ...(agent === undefined ? { routeStale: true } : {}),
             };
         }
-        if (!(await (this.opts.waitForBoundary ?? waitForPaseoWakeBoundary)(agent))) {
+        remaining = remainingMs();
+        if (remaining === 0)
+            return budgetUnavailable();
+        if (!(await (this.opts.waitForBoundary ?? waitForPaseoWakeBoundary)(agent, remaining))) {
             return {
                 outcome: 'unavailable',
                 signature: 'boundary_unavailable',
@@ -71,8 +87,11 @@ export class PaseoAdapter {
         }
         if (!(await beforeSend()))
             return { outcome: 'cancelled' };
+        remaining = remainingMs();
+        if (remaining === 0)
+            return budgetUnavailable();
         try {
-            (this.opts.sendWake ?? sendPaseoWake)({ agentId, prompt: payload });
+            (this.opts.sendWake ?? sendPaseoWake)({ agentId, prompt: payload }, { timeoutMs: remaining });
             return { outcome: 'accepted' };
         }
         catch (error) {

package/dist/paseo-state.d.ts

@@ -8,4 +8,4 @@ export declare function discoverPaseoAgents(timeoutMs?: number): {
     agents: PaseoAgent[];
     error?: string;
 };
-export declare function waitForPaseoWakeBoundary(agent: Pick<PaseoAgent, 'id' | 'status'>): Promise<boolean>;
+export declare function waitForPaseoWakeBoundary(agent: Pick<PaseoAgent, 'id' | 'status'>, timeoutMs?: number): Promise<boolean>;

package/dist/paseo-state.js

@@ -22,10 +22,10 @@ export function discoverPaseoAgents(timeoutMs = 5000) {
         return { agents: [], error: error instanceof Error ? error.message : String(error) };
     }
 }
-export async function waitForPaseoWakeBoundary(agent) {
+export async function waitForPaseoWakeBoundary(agent, timeoutMs = 30_000) {
     if (agent.status === 'idle')
         return true;
     if (agent.status !== 'running')
         return false;
-    return waitForPaseoToolBoundary(agent.id);
+    return waitForPaseoToolBoundary(agent.id, { timeoutMs });
 }

package/dist/ports.d.ts

@@ -17,6 +17,11 @@ export interface SquareArtifactPort {
 }
 /** 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. */
+    probe?(route: WakeRoute): Promise<boolean | {
+        readonly outcome: 'not-capable';
+        readonly diagnostic?: string;
+    }>;
     attempt(request: WakeRequest, timeoutMs: number): Promise<WakeOutcome>;
     /** Optional route retirement supplied by the concrete executor adapter. */
     invalidate?(request: WakeRequest): Promise<void>;
@@ -65,6 +70,11 @@ export type WakeOutcome = {
     readonly message?: string;
     readonly attemptN?: number;
     readonly unavailable?: boolean;
+    readonly retainRoute?: boolean;
+    readonly routeStale?: boolean;
+} | {
+    readonly outcome: 'not-capable';
+    readonly diagnostic?: string;
 } | {
     readonly outcome: 'unknown';
     readonly diagnostic?: string;
@@ -98,6 +108,7 @@ export interface DeliveryResult {
     readonly accepted: number;
     readonly failed: number;
     readonly unknown: number;
+    readonly notCapable: number;
 }
 export interface DeliverPendingInput {
     readonly artifact: SquareArtifactPort;

package/dist/presence.js

@@ -5,7 +5,7 @@ import { recordObservation } from './runtime.js';
 import { catchUp as actionCatchUp } from './square-actions.js';
 function operationContext(square) {
     return 'artifact' in square
-        ? { artifact: square.artifact, clock: square.clock }
+        ? { artifact: square.artifact, clock: square.clock, location: square.location, hostLedger: square.hostLedger, wakeTransport: square.wakeTransport, env: square.env }
         : { artifact: square.cell, clock: square.clock };
 }
 export async function catchUp(square, name, options = {}, deriveDelivery = deriveDeliveryModel) {

package/dist/registry.js

@@ -26,7 +26,7 @@ async function writePresence(sessionId, name, squarePath, options, done, scope =
     return; const env = options.env ?? process.env; const channel = options.channel ?? 'unknown'; const port = ledger(env, scope); const location = await canonicalSquarePath(squarePath); if (done)
     await port.removePresence({ location, participant: name, session: sessionId, channel });
 else
-    await port.ensurePresence({ location, participant: name, session: sessionId, channel, route: options.route, updatedAt: options.at ?? Date.now() }); }
+    await port.ensurePresence({ location, participant: name, session: sessionId, channel, updatedAt: options.at ?? Date.now() }); }
 export function recordJoin(sessionId, name, squarePath, options = {}) { return writePresence(sessionId, name, squarePath, options, false); }
 export async function recordDone(sessionId, name, squarePath, options = {}) {
     await writePresence(sessionId, name, squarePath, options, true);
@@ -64,17 +64,16 @@ function addLocalSession(identities, sessionId, channel, child, paseoAgentId) {
 export function localSessionIdentities(env = process.env) { const paseoAgentId = env.PASEO_AGENT_ID?.trim() || undefined; const identities = []; for (const source of LOCAL_SESSION_SOURCES)
     addLocalSession(identities, env[source.variable]?.trim(), source.channel, source.child !== undefined && env[source.child] === '1', paseoAgentId); addLocalSession(identities, paseoAgentId, 'paseo', false, paseoAgentId); return identities; }
 export function hasAutomaticDeliveryIdentity(env = process.env) { return localSessionIdentities(env).length > 0; }
-function callableRoute(sessionId, channel, env) { if (channel === 'codex' && env.CODEX_THREAD_ID?.trim() === sessionId)
-    return { kind: 'codex-queue', address: { threadId: sessionId } }; if (channel === 'paseo' && env.PASEO_AGENT_ID?.trim() === sessionId)
-    return { kind: 'paseo', address: { agentId: sessionId } }; return undefined; }
-export async function recordLocalJoin(name, squarePath, env = process.env) { const at = Date.now(); const identities = localSessionIdentities(env); const current = await lookupParticipant(squarePath, name, at, env); for (const binding of current)
-    await recordDone(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, at, env }); for (const identity of identities)
-    await recordJoin(identity.sessionId, name, squarePath, { ...identity, at, env }); }
-export async function recordLocalDone(name, squarePath, env = process.env) { const at = Date.now(); const current = await lookupParticipant(squarePath, name, at, env); for (const binding of current)
+export async function recordLocalJoin(name, squarePath, env = process.env) { const at = Date.now(); const identities = localSessionIdentities(env); const current = await lookupParticipant(squarePath, name, at, env); for (const identity of identities) {
+    for (const binding of current.filter((item) => item.sessionId === identity.sessionId))
+        await recordDone(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, at, env });
+    await recordJoin(identity.sessionId, name, squarePath, { ...identity, at, env });
+} }
+export async function recordLocalDone(name, squarePath, env = process.env) { const at = Date.now(); const identities = new Set(localSessionIdentities(env).map((identity) => identity.sessionId)); const current = (await lookupParticipant(squarePath, name, at, env)).filter((binding) => identities.has(binding.sessionId)); for (const binding of current)
     await recordDone(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, at, env }); }
-export async function recordSessionJoin(sessionId, name, squarePath, channel, env = process.env) { const at = Date.now(); const current = await lookupParticipant(squarePath, name, at, env); for (const binding of current) {
+export async function recordSessionJoin(sessionId, name, squarePath, channel, env = process.env) { const at = Date.now(); const current = (await lookupParticipant(squarePath, name, at, env)).filter((binding) => binding.sessionId === sessionId); for (const binding of current) {
     await recordDone(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, at, env });
     await writePresence(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, at, env }, true, 'user');
-} const route = callableRoute(sessionId, channel, env); await recordJoin(sessionId, name, squarePath, { channel, at, env }); await writePresence(sessionId, name, squarePath, { channel, route, at, env }, false, 'user'); return sessionId; }
+} await recordJoin(sessionId, name, squarePath, { channel, at, env }); await writePresence(sessionId, name, squarePath, { channel, at, env }, false, 'user'); return sessionId; }
 export async function recordSessionDone(sessionId, name, squarePath, channel, env = process.env) { const canonicalPath = await canonicalSquarePath(squarePath); const binding = (await lookupSessionBindings(sessionId, Date.now(), env)).find((item) => item.squarePath === canonicalPath && sameName(item.name, name) && item.channel === channel); if (binding === undefined)
     return false; const options = { channel, at: Date.now(), env }; await recordDone(sessionId, binding.name, binding.squarePath, options); await writePresence(sessionId, binding.name, binding.squarePath, options, true, 'user'); return true; }

package/dist/routes.d.ts

@@ -1,7 +1,26 @@
-import { type WakeRoute } from './model.js';
+import { type WakeRoute, type WakeRouteKind } from './model.js';
 export { WAKE_ROUTE_KINDS } from './model.js';
 export type { WakeRoute, WakeRouteKind } from './model.js';
 export declare const ROUTE_FRESH_MS: number;
+export type WakeBoundaryProvider = 'codex' | 'claude' | 'opencode' | 'pi' | 'paseo';
+export interface WakeBoundary {
+    readonly location: string;
+    readonly participant: string;
+    readonly sessionId: string;
+    readonly provider: WakeBoundaryProvider;
+}
+export interface WakeRouteCapabilities {
+    readonly canUse: (kind: WakeRouteKind, address: Readonly<Record<string, string>>) => boolean;
+}
+export declare function defaultWakeRouteCapabilities(hostLedger?: import('./host-ledger.js').HostLedgerPort): Promise<WakeRouteCapabilities>;
+/** Pure, ordered route precedence. Capability predicates own adapter and scope checks. */
+export declare function selectPrimaryWakeRoute(input: {
+    readonly boundary: WakeBoundary;
+    readonly env: NodeJS.ProcessEnv;
+    readonly capabilities: WakeRouteCapabilities;
+}): Omit<WakeRoute, 'updatedAt'> | undefined;
+export declare function routeIdentityKey(route: Pick<WakeRoute, 'location' | 'participant' | 'sessionId'>, location?: string): string;
+export declare function resolvePrimaryWakeRoute(boundary: WakeBoundary, env: NodeJS.ProcessEnv, capabilities: WakeRouteCapabilities): Omit<WakeRoute, 'updatedAt'> | undefined;
 export declare function readWakeRoutes(opts?: {
     location?: string;
     participant?: string;
@@ -14,7 +33,12 @@ export declare function upsertWakeRoute(route: Omit<WakeRoute, 'updatedAt'>, opt
     at?: number;
     env?: NodeJS.ProcessEnv;
 }): Promise<void>;
+export declare function publishWakeRoute(artifact: import('./ports.js').SquareArtifactPort, route: Omit<WakeRoute, 'updatedAt'>, opts?: {
+    at?: number;
+}): Promise<void>;
 export declare function retireWakeRoute(route: WakeRoute, opts?: {
     at?: number;
     env?: NodeJS.ProcessEnv;
 }): Promise<void>;
+export declare function retireWakeRouteFromArtifact(artifact: import('./ports.js').SquareArtifactPort, route: Pick<WakeRoute, 'location' | 'participant' | 'sessionId'>): Promise<void>;
+export declare function canonicalRouteLocation(location: string): Promise<string>;

package/dist/routes.js

@@ -1,9 +1,110 @@
-import os from 'node:os';
+import fs from 'node:fs';
 import path from 'node:path';
-import { createHostLedgerPort } from './host-ledger-file-adapter.js';
+import { nameKey } from './model.js';
+import { openSquare } from './square-file-adapter.js';
+import { closeOpenSquare } from './open-square.js';
 export { WAKE_ROUTE_KINDS } from './model.js';
 export const ROUTE_FRESH_MS = 24 * 60 * 60 * 1000;
-function ledger(env) { return createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? path.join(os.homedir(), '.square', 'host-ledger'), writableScope: 'user', readableScopes: ['user'] }); }
-export async function readWakeRoutes(opts = {}) { const now = opts.now ?? Date.now(); const records = await ledger(opts.env ?? process.env).listPresence({ location: opts.location, participant: opts.participant, session: opts.sessionId, now, scopes: ['user'] }); return records.flatMap((record) => record.route === undefined || (opts.freshOnly === true && now - (record.updatedAt ?? 0) >= ROUTE_FRESH_MS) ? [] : [{ location: record.location, participant: record.participant, sessionId: record.session, channel: record.channel, kind: record.route.kind, address: { ...record.route.address }, updatedAt: record.updatedAt ?? 0 }]); }
-export async function upsertWakeRoute(route, opts = {}) { await ledger(opts.env ?? process.env).ensurePresence({ location: route.location, participant: route.participant, session: route.sessionId, channel: route.channel, route: { kind: route.kind, address: route.address }, updatedAt: opts.at ?? Date.now() }); }
-export async function retireWakeRoute(route, opts = {}) { await ledger(opts.env ?? process.env).ensurePresence({ location: route.location, participant: route.participant, session: route.sessionId, channel: route.channel, updatedAt: opts.at ?? Date.now() }); }
+export async function defaultWakeRouteCapabilities(hostLedger) {
+    let userCapable = hostLedger !== undefined;
+    if (hostLedger !== undefined) {
+        try {
+            await hostLedger.listPresence({ scopes: ['user'], now: Date.now() });
+        }
+        catch {
+            userCapable = false;
+        }
+    }
+    const available = new Set();
+    try {
+        const { CodexQueueAdapter } = await import('./codex-queue.js');
+        available.add(new CodexQueueAdapter().kind);
+    }
+    catch { /* optional */ }
+    try {
+        const { PaseoAdapter } = await import('./paseo-delivery.js');
+        available.add(new PaseoAdapter().kind);
+    }
+    catch { /* optional */ }
+    return { canUse: (kind, address) => userCapable && available.has(kind) && Object.values(address).every((value) => value.trim() !== '') };
+}
+function nativeCandidate(boundary) {
+    if (boundary.provider === 'codex')
+        return { kind: 'codex-queue', address: { threadId: boundary.sessionId } };
+    if (boundary.provider === 'claude')
+        return { kind: 'claude-native', address: { sessionId: boundary.sessionId } };
+    if (boundary.provider === 'opencode')
+        return { kind: 'opencode-server', address: { sessionId: boundary.sessionId } };
+    if (boundary.provider === 'pi')
+        return { kind: 'pi-extension', address: { sessionId: boundary.sessionId } };
+    return undefined;
+}
+/** Pure, ordered route precedence. Capability predicates own adapter and scope checks. */
+export function selectPrimaryWakeRoute(input) {
+    const { boundary, env, capabilities } = input;
+    const paseoAgentId = env.PASEO_AGENT_ID?.trim();
+    const candidates = [];
+    if (paseoAgentId)
+        candidates.push({ kind: 'paseo', address: { agentId: paseoAgentId } });
+    const native = nativeCandidate(boundary);
+    if (native)
+        candidates.push(native);
+    const chosen = candidates.find((candidate) => Object.values(candidate.address).every((value) => value.trim() !== '') && capabilities.canUse(candidate.kind, candidate.address));
+    return chosen === undefined ? undefined : { location: boundary.location, participant: boundary.participant, sessionId: boundary.sessionId, channel: boundary.provider === 'paseo' ? 'paseo' : boundary.provider === 'claude' ? 'claude-code' : boundary.provider, ...chosen };
+}
+export function routeIdentityKey(route, location = route.location) {
+    return JSON.stringify([location, nameKey(route.participant), route.sessionId]);
+}
+export function resolvePrimaryWakeRoute(boundary, env, capabilities) {
+    return selectPrimaryWakeRoute({ boundary, env, capabilities });
+}
+async function withArtifact(location, fn) {
+    if (location === undefined)
+        return undefined;
+    try {
+        await fs.promises.access(location);
+        const square = await openSquare(location);
+        try {
+            return await fn(square);
+        }
+        finally {
+            await closeOpenSquare(square);
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function readWakeRoutes(opts = {}) {
+    const now = opts.now ?? Date.now();
+    const canonicalLocation = opts.location === undefined ? undefined : await canonicalRouteLocation(opts.location);
+    const routes = await withArtifact(canonicalLocation, async (square) => (await square.artifact.read()).state.routes ?? []) ?? [];
+    const filtered = routes.filter((route) => (opts.participant === undefined || nameKey(route.participant) === nameKey(opts.participant)) && (opts.sessionId === undefined || route.sessionId === opts.sessionId) && (!opts.freshOnly || now - route.updatedAt < ROUTE_FRESH_MS));
+    const canonicalized = await Promise.all(filtered.map(async (route) => ({ ...route, location: await canonicalRouteLocation(route.location), address: { ...route.address } })));
+    return canonicalLocation === undefined ? canonicalized : canonicalized.filter((route) => route.location === canonicalLocation);
+}
+export async function upsertWakeRoute(route, opts = {}) {
+    const location = await canonicalRouteLocation(route.location);
+    await withArtifact(location, async (square) => publishWakeRoute(square.artifact, { ...route, location }, opts));
+}
+export async function publishWakeRoute(artifact, route, opts = {}) {
+    const location = await canonicalRouteLocation(route.location);
+    await artifact.transact((state) => ({ state: { ...state, routes: [...(state.routes ?? []).filter((item) => routeIdentityKey(item) !== routeIdentityKey({ ...route, location })), { ...route, location, participant: route.participant, updatedAt: opts.at ?? Date.now() }] }, result: undefined }));
+}
+export async function retireWakeRoute(route, opts = {}) {
+    const location = await canonicalRouteLocation(route.location);
+    await withArtifact(location, async (square) => retireWakeRouteFromArtifact(square.artifact, { ...route, location }));
+}
+export async function retireWakeRouteFromArtifact(artifact, route) {
+    const location = await canonicalRouteLocation(route.location);
+    await artifact.transact((state) => ({ state: { ...state, routes: (state.routes ?? []).filter((item) => routeIdentityKey(item) !== routeIdentityKey({ ...route, location })) }, result: undefined }));
+}
+export async function canonicalRouteLocation(location) {
+    const absolute = path.resolve(location);
+    try {
+        return await fs.promises.realpath(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}

package/dist/square-actions.d.ts

@@ -8,6 +8,7 @@ export interface OperationContext {
     readonly clock: () => number;
     readonly location?: string;
     readonly hostLedger?: HostLedgerPort;
+    readonly wakeTransport?: import('./ports.js').WakeTransportPort;
     readonly env?: NodeJS.ProcessEnv;
 }
 export declare function catchUp(square: OperationContext, name: string, options?: CatchOptions, project?: (state: SquareState) => CatchProjection): Promise<CatchResult>;

package/dist/square-actions.js

@@ -2,7 +2,9 @@ import { extractMentions, formatActivityId, parseActivityId } from './square-cor
 import { coreDone, coreHold, coreIgnore, coreListen, coreListening, coreResume, decideAct, decideImplicitJoin, decideJoin } from './decisions.js';
 import { SquareError } from './model.js';
 import { participantIdentity } from './participant-identity.js';
+import { deliverPending } from './delivery-operations.js';
 import { decideCatch } from './catch-decisions.js';
+import { publishWakeRoute, retireWakeRouteFromArtifact, resolvePrimaryWakeRoute, defaultWakeRouteCapabilities } from './routes.js';
 function processIdentity(env) {
     const choices = [
         [env.CLAUDE_CODE_SESSION_ID, 'claude-code'], [env.CODEX_THREAD_ID, 'codex'],
@@ -11,6 +13,25 @@ function processIdentity(env) {
     const found = choices.find(([session]) => session?.trim());
     return found === undefined ? { session: `process:${process.pid}`, channel: 'unknown' } : { session: found[0].trim(), channel: found[1] };
 }
+async function publishIdentityRoute(context, participant) {
+    if (context.location === undefined || context.location === 'memory')
+        return;
+    const identity = processIdentity(context.env ?? process.env);
+    if (context.hostLedger === undefined)
+        return;
+    const provider = identity.channel === 'claude-code' ? 'claude' : identity.channel === 'opencode' ? 'opencode' : identity.channel === 'pi' ? 'pi' : identity.channel === 'paseo' ? 'paseo' : 'codex';
+    const capabilities = await defaultWakeRouteCapabilities(context.hostLedger);
+    const route = await resolvePrimaryWakeRoute({ location: context.location, participant, sessionId: identity.session, provider }, context.env ?? process.env, capabilities);
+    if (route === undefined)
+        return;
+    await publishWakeRoute(context.artifact, route, { at: context.clock() }).catch(() => undefined);
+}
+async function retireIdentityRoute(context, participant) {
+    if (context.location === undefined || context.location === 'memory')
+        return;
+    const identity = processIdentity(context.env ?? process.env);
+    await retireWakeRouteFromArtifact(context.artifact, { location: context.location, participant, sessionId: identity.session }).catch(() => undefined);
+}
 /** Presence is best effort and runs only after the artifact mutation commits. */
 async function ensureLocalPresence(context, participant) {
     if (context.hostLedger === undefined || context.location === undefined || context.location === 'memory')
@@ -48,6 +69,7 @@ export async function catchUp(square, name, options = {}, project) {
             return { ...(decision.changed ? { state } : {}), result: { version, decision } };
         });
         await ensureLocalPresence(square, name);
+        await publishIdentityRoute(square, name);
         if (attempt.decision.delivered.length > 0 || idle === 0) {
             return {
                 activities: attempt.decision.delivered.map((activity) => exposeCaught(activity, attempt.decision.perceptions.get(activity.index) ?? 'full')),
@@ -103,6 +125,7 @@ export async function join(square, name) {
         return { state, result: { name: decision.joinedName, stored: committedActivity(storeActs(state, [decision.joinAct]), 'join') } };
     });
     await ensureLocalPresence(square, committed.name);
+    await publishIdentityRoute(square, committed.name);
     return { name: committed.name, activity: committed.stored === null ? null : exposeActivity(committed.stored) };
 }
 export async function implicitJoin(square, name) {
@@ -114,6 +137,10 @@ export async function implicitJoin(square, name) {
         return { state, result: { name: decision.joinedName, state: decision.state, stored: committedActivity(storeActs(state, [decision.joinAct]), 'join') } };
     });
     await ensureLocalPresence(square, committed.name);
+    if (committed.state === 'done')
+        await retireIdentityRoute(square, committed.name);
+    else
+        await publishIdentityRoute(square, committed.name);
     return { name: committed.name, state: committed.state, activity: committed.stored === null ? null : exposeActivity(committed.stored) };
 }
 export async function express(square, name, body, options = {}) {
@@ -139,7 +166,15 @@ export async function express(square, name, body, options = {}) {
         return { state, result: { stored } };
     });
     await ensureLocalPresence(square, name);
-    return { activity: exposeActivity(committed.stored) };
+    await publishIdentityRoute(square, name);
+    let delivery;
+    if (square.wakeTransport !== undefined && square.hostLedger !== undefined && square.location !== undefined && square.location !== 'memory') {
+        delivery = await deliverPending({ artifact: square.artifact, hostLedger: square.hostLedger, transport: square.wakeTransport, location: square.location, activity: committed.stored.index, now }).catch(() => ({ attempted: 0, accepted: 0, failed: 0, unknown: 0, notCapable: 1 }));
+    }
+    else {
+        delivery = { attempted: 0, accepted: 0, failed: 0, unknown: 0, notCapable: 1 };
+    }
+    return { activity: exposeActivity(committed.stored), delivery };
 }
 async function landListenerChange(square, verb, actor, target) {
     const now = square.clock();
@@ -160,6 +195,8 @@ async function landCore(square, verb, actor, body = '') {
         const act = verb === 'done' ? coreDone(state, actor, body, now) : verb === 'hold' ? coreHold(state, actor, body, now) : coreResume(state, actor, now);
         return { state, result: committedActivity(storeActs(state, [act]), verb) };
     });
+    if (verb === 'done')
+        await retireIdentityRoute(square, actor);
     return { activity: exposeActivity(stored) };
 }
 export function done(square, name, body = '') { return landCore(square, 'done', name, body); }

package/dist/square-facade.d.ts

@@ -1,5 +1,5 @@
 import type { ActivityId, Perception, Reach } from './square-core.js';
-import type { HostLedgerPort } from './ports.js';
+import type { HostLedgerPort, WakeTransportPort, DeliveryResult } from './ports.js';
 export interface Activity {
     readonly id: ActivityId;
     readonly at: number;
@@ -20,6 +20,7 @@ export interface ExpressOptions {
 }
 export interface ExpressResult {
     readonly activity: Activity;
+    readonly delivery?: DeliveryResult;
 }
 export interface ListenerChangeResult {
     readonly activity: Activity | null;
@@ -68,6 +69,7 @@ export type SquareSource = {
 export interface OpenOptions {
     clock?: () => number;
     hostLedger?: HostLedgerPort;
+    wakeTransport?: WakeTransportPort;
     env?: NodeJS.ProcessEnv;
 }
 export interface SquareAtInput extends SquareSource, OpenOptions {
@@ -78,6 +80,7 @@ export interface SquareBuildInput extends SquareSource {
     throttlePerMinute?: number;
     clock?: () => number;
     hostLedger?: HostLedgerPort;
+    wakeTransport?: WakeTransportPort;
     env?: NodeJS.ProcessEnv;
 }
 export interface Participant {

package/dist/square-file-adapter.d.ts

@@ -11,9 +11,10 @@ export interface SquareBuildOptions {
     throttlePerMinute?: number;
     clock?: () => number;
     hostLedger?: HostLedgerPort;
+    wakeTransport?: import('./ports.js').WakeTransportPort;
     env?: NodeJS.ProcessEnv;
 }
-export declare function openSquare(squarePath: string, options?: Pick<SquareBuildOptions, 'clock' | 'hostLedger' | 'env'>): Promise<OpenSquare>;
+export declare function openSquare(squarePath: string, options?: Pick<SquareBuildOptions, 'clock' | 'hostLedger' | 'wakeTransport' | 'env'>): Promise<OpenSquare>;
 export declare function probeSquare(squarePath: string): Promise<OpenSquare | undefined>;
 export declare function buildSquare(squarePath: string, options: SquareBuildOptions): Promise<OpenSquare>;
 export declare function buildMemorySquare(options: SquareBuildOptions): OpenSquare;