@astrosheep/square 0.3.31 → 0.3.32

package/claude-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.31",
+  "version": "0.3.32",
   "description": "Native Claude Code turn-boundary delivery for Square participants",
   "author": {
     "name": "Square"

package/codex-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.31",
+  "version": "0.3.32",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/dist/activity.js

@@ -11,6 +11,8 @@ import { Square } from './square-wiring.js';
 import { activityPresentation, resolveParticipant } from './views.js';
 import { formatActivityId } from './square-core.js';
 import { formatTimestamp } from './time.js';
+import { createHostLedgerPort } from './host-ledger-file-adapter.js';
+import { createDefaultWakeTransport } from './notifications.js';
 function draftDirFor(squarePath) {
     return path.join(path.dirname(squarePath), 'drafts');
 }
@@ -66,7 +68,9 @@ export async function cmdActivity(squarePath, name, activity, resolveBody, opts)
     const noWait = opts.noWait ?? false;
     const reach = opts.reach === 'bell' ? 'bell' : undefined;
     let announcedWait;
-    const square = await Square.at({ path: squarePath, clock: nowMs });
+    const ledgerRoot = process.env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(process.env.SQUARE_REGISTRY);
+    const hostLedger = createHostLedgerPort({ userPath: process.env.SQUARE_HOST_LEDGER_USER ?? ledgerRoot, localPath: process.env.SQUARE_HOST_LEDGER_LOCAL ?? ledgerRoot });
+    const square = await Square.at({ path: squarePath, clock: nowMs, hostLedger, wakeTransport: await createDefaultWakeTransport(hostLedger, nowMs) });
     try {
         const participant = await square.join(name);
         while (true) {
@@ -80,11 +84,8 @@ export async function cmdActivity(squarePath, name, activity, resolveBody, opts)
                     ...(reach === undefined ? {} : { reach }),
                     ...(opts.reply === undefined ? {} : { reply: formatActivityId(opts.reply) }),
                 });
-                try {
-                }
-                catch {
-                    // Compatibility wake is post-commit and cannot undo the activity.
-                }
+                if (result.delivery?.notCapable)
+                    process.stderr.write(`! wake not-capable: ${result.delivery.notCapable}\n`);
                 const freshSquare = await openSquare(squarePath, { clock: nowMs });
                 const fresh = await activityPresentation(freshSquare, knownName).finally(() => closeOpenSquare(freshSquare));
                 const headerCount = fresh.participantCount;

package/dist/artifact.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { TextDecoder } from 'node:util';
 import zlib from 'node:zlib';
-import { InternalSquareError, SquareError, } from './model.js';
+import { isWakeRouteKind, InternalSquareError, SquareError, } from './model.js';
 import { parseActivityId } from './square-core.js';
 const SQUARE_MAGIC = Buffer.from('SQUARE01', 'ascii');
 const LENGTH_BYTES = 4;
@@ -138,13 +138,14 @@ function validateActs(value) {
 }
 function validateSquareState(value) {
     if (!isObject(value)
-        || !hasExactKeys(value, ['hardCap', 'preamble', 'warmup', 'acts', 'runtime'], ['throttlePerMinute'])
+        || !hasExactKeys(value, ['hardCap', 'preamble', 'warmup', 'acts', 'runtime'], ['throttlePerMinute', 'routes'])
         || !(value.hardCap === null || (Number.isSafeInteger(value.hardCap) && value.hardCap > 0))
         || (value.throttlePerMinute !== undefined
             && (!Number.isSafeInteger(value.throttlePerMinute) || value.throttlePerMinute <= 0))
         || !isStringArray(value.preamble)
         || !isStringArray(value.warmup)
         || !validateActs(value.acts)
+        || (value.routes !== undefined && (!Array.isArray(value.routes) || !value.routes.every((route) => isObject(route) && isWakeRouteKind(route.kind) && typeof route.location === 'string' && typeof route.participant === 'string' && typeof route.sessionId === 'string' && typeof route.channel === 'string' && isObject(route.address) && Object.values(route.address).every((item) => typeof item === 'string') && typeof route.updatedAt === 'number')))
         || !validateRuntime(value.runtime)) {
         throw invalidArtifact('snapshot schema is malformed.');
     }
@@ -241,6 +242,7 @@ export function createSquareState(options, snippet) {
         preamble: normalizedLines(snippet),
         warmup: normalizedLines(guides.join('\n\n')),
         acts: [],
+        routes: [],
         runtime: emptyRuntimeState(),
     };
 }

package/dist/automatic-session.js

@@ -7,6 +7,7 @@ import { entryPresentation } from './views.js';
 import { automaticParticipant } from './participant-identity.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 import { projectSessionBindings } from './square-projections.js';
+import { publishWakeRoute, retireWakeRouteFromArtifact, resolvePrimaryWakeRoute, defaultWakeRouteCapabilities } from './routes.js';
 export { automaticParticipant } from './participant-identity.js';
 const providerEnv = {
     codex: 'CODEX_THREAD_ID',
@@ -56,7 +57,17 @@ export async function automaticSessionStart(provider, sessionId, cwd, env = proc
         const implicit = await square.implicitJoin(name);
         if (implicit.state === 'done')
             return undefined;
-        await hostLedgerForEnv(env).ensurePresence({ location: squarePath, participant: name, session: sessionId, channel: provider === 'claude' ? 'claude-code' : provider, updatedAt: Date.now() });
+        const route = resolvePrimaryWakeRoute({ location: squarePath, participant: name, sessionId, provider }, env, await defaultWakeRouteCapabilities(hostLedgerForEnv(env)));
+        if (route !== undefined) {
+            const publisher = await openSquare(squarePath, { hostLedger: hostLedgerForEnv(scopedEnv), env: scopedEnv });
+            try {
+                await publishWakeRoute(publisher.artifact, route, { at: Date.now() });
+            }
+            finally {
+                await closeOpenSquare(publisher);
+            }
+        }
+        await hostLedgerForEnv(env).ensurePresence({ location: squarePath, participant: name, session: sessionId, channel: provider === 'claude' ? 'claude-code' : provider, updatedAt: Date.now() }, 'user');
         await square.reconcileBinding();
         return undefined;
     }
@@ -87,6 +98,13 @@ export async function automaticSessionEnd(provider, sessionId, cwd, env = proces
         const participant = await square.join(binding.participant);
         await participant.done();
         await square.reconcileBinding();
+        const cleanup = await openSquare(squarePath);
+        try {
+            await retireWakeRouteFromArtifact(cleanup.artifact, { location: squarePath, participant: binding.participant, sessionId });
+        }
+        finally {
+            await closeOpenSquare(cleanup);
+        }
     }
     finally {
         await square.close();

package/dist/claude-hook.d.ts

@@ -1,9 +1,10 @@
 import type { InboxMembership } from './model.js';
+import type { WakeAdapter } from './delivery.js';
 export interface NativeHookInput {
     session_id?: unknown;
     hook_event_name?: unknown;
     cwd?: unknown;
 }
 export declare function runClaudeHookAsync(inputText: string, env?: NodeJS.ProcessEnv): Promise<string>;
-export declare function claudeHookResponse(input: NativeHookInput, lookup?: (sessionId: string, env?: NodeJS.ProcessEnv) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv): Promise<object | undefined>;
+export declare function claudeHookResponse(input: NativeHookInput, lookup?: (sessionId: string, env?: NodeJS.ProcessEnv) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv, deliveryAdapters?: WakeAdapter[]): Promise<object | undefined>;
 export declare function runClaudeHook(inputText: string, env?: NodeJS.ProcessEnv): Promise<string>;

package/dist/claude-hook.js

@@ -1,6 +1,7 @@
 import { presentPendingAtBoundary } from './boundary-presentation.js';
 import { sessionInbox } from './inbox.js';
 import { automaticSessionEnd, automaticSessionStart } from './automatic-session.js';
+import { sweepPrivilegedPending } from './notifications.js';
 export async function runClaudeHookAsync(inputText, env = process.env) {
     let input;
     try {
@@ -34,12 +35,14 @@ export async function runClaudeHookAsync(inputText, env = process.env) {
     }
     return runClaudeHook(inputText, env);
 }
-export async function claudeHookResponse(input, lookup = sessionInbox, env = process.env) {
+export async function claudeHookResponse(input, lookup = sessionInbox, env = process.env, deliveryAdapters) {
     if (typeof input.session_id !== 'string' || input.session_id === '')
         return undefined;
     if (input.hook_event_name !== 'PostToolBatch')
         return undefined;
-    return presentPendingAtBoundary(input.session_id, (context) => ({ hookSpecificOutput: { hookEventName: 'PostToolBatch', additionalContext: context } }), lookup, env);
+    const response = await presentPendingAtBoundary(input.session_id, (context) => ({ hookSpecificOutput: { hookEventName: 'PostToolBatch', additionalContext: context } }), lookup, env);
+    await sweepPrivilegedPending(typeof input.cwd === 'string' ? input.cwd : process.cwd(), env, deliveryAdapters).catch(() => undefined);
+    return response;
 }
 export async function runClaudeHook(inputText, env = process.env) {
     let input;

package/dist/cli/square-commands.js

@@ -4,12 +4,12 @@ import { participantCommandPrefix, participantIdentity, renderEventCli, renderAm
 import { hasAutomaticDeliveryIdentity, } from '../registry.js';
 import { createHostLedgerPort } from '../host-ledger-file-adapter.js';
 import { projectLocalParticipantBinding, sessionIdsFromEnvironment } from '../square-projections.js';
-import { sweepPendingNotifications } from '../notifications.js';
 import { nowMs } from '../runtime.js';
 import { createSquare, openSquare } from '../square-file-adapter.js';
 import { closeOpenSquare } from '../open-square.js';
 import { openParticipant, Square } from '../square-wiring.js';
 import { entryPresentation, eventPresentation } from '../views.js';
+import { createDefaultWakeTransport } from '../notifications.js';
 import { fail, parseHardCap, parsePositiveInteger, readStdin, requireParticipant, requireSquarePath, requireValue, resolveBody, usage, } from './context.js';
 function parseBuild(argv) {
     const options = { force: false, hardCap: null };
@@ -86,7 +86,8 @@ export const joinCommand = {
         const beforeSquare = await openSquare(squarePath, { clock: nowMs });
         const before = await entryPresentation(beforeSquare, intent.name, intent.lastN);
         await closeOpenSquare(beforeSquare);
-        const square = await Square.at({ path: squarePath, clock: nowMs });
+        const hostLedger = createHostLedgerPort();
+        const square = await Square.at({ path: squarePath, clock: nowMs, hostLedger, wakeTransport: await createDefaultWakeTransport(hostLedger, nowMs) });
         try {
             const reconnect = before.joined
                 && await projectLocalParticipantBinding({
@@ -109,8 +110,7 @@ export const joinCommand = {
             const afterSquare = await openSquare(squarePath, { clock: nowMs });
             const after = await entryPresentation(afterSquare, joinedName, intent.lastN);
             await closeOpenSquare(afterSquare);
-            await square.reconcileBinding();
-            await sweepPendingNotifications(squarePath);
+            await square.reconcileBinding().catch(() => undefined);
             const activities = after.recentActivities.map((event) => renderAmbientEvent(event, joinedName, {
                 now: nowMs(),
                 preview: intent.lastN === null ? undefined : 200,
@@ -182,7 +182,6 @@ export const expressCommand = {
     parse: parseActivity,
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
-        await sweepPendingNotifications(squarePath);
         const body = await resolveBody(intent.activity);
         const reachArg = intent.reach === 'bell' ? ' --bell' : '';
         await cmdActivity(squarePath, intent.name, body, (value) => value, {

package/dist/codex-hook.d.ts

@@ -1,10 +1,11 @@
 import type { InboxMembership } from './model.js';
+import type { WakeAdapter } from './delivery.js';
 export interface CodexHookInput {
     session_id?: unknown;
     hook_event_name?: unknown;
     cwd?: unknown;
     source?: unknown;
 }
-export declare function codexHookResponse(input: CodexHookInput, lookup?: (sessionId: string, env?: NodeJS.ProcessEnv) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv): Promise<object | undefined>;
+export declare function codexHookResponse(input: CodexHookInput, lookup?: (sessionId: string, env?: NodeJS.ProcessEnv) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv, deliveryAdapters?: WakeAdapter[]): Promise<object | undefined>;
 export declare function runCodexHook(inputText: string, env?: NodeJS.ProcessEnv): Promise<string>;
 export declare function runCodexHookAsync(inputText: string, env?: NodeJS.ProcessEnv): Promise<string>;

package/dist/codex-hook.js

@@ -2,11 +2,12 @@ import { presentPendingAtBoundary } from './boundary-presentation.js';
 import { sessionInbox } from './inbox.js';
 import { automaticSessionEnd, automaticSessionStart } from './automatic-session.js';
 import { clearCodexBoundary, recordCodexBoundary } from './codex-boundary-state.js';
+import { sweepPrivilegedPending } from './notifications.js';
 const CODEX_HOOK_EVENTS = {
     PostToolUse: 'PostToolUse',
     Stop: 'Stop',
 };
-export async function codexHookResponse(input, lookup = sessionInbox, env = process.env) {
+export async function codexHookResponse(input, lookup = sessionInbox, env = process.env, deliveryAdapters) {
     if (typeof input.session_id !== 'string' || input.session_id === '')
         return undefined;
     if (typeof input.hook_event_name !== 'string')
@@ -15,9 +16,11 @@ export async function codexHookResponse(input, lookup = sessionInbox, env = proc
     if (hookEventName === undefined)
         return undefined;
     await recordCodexBoundary(input.session_id, hookEventName === 'Stop' ? 'Stop' : 'non-stop', env);
-    return presentPendingAtBoundary(input.session_id, (context) => hookEventName === 'Stop'
+    const response = await presentPendingAtBoundary(input.session_id, (context) => hookEventName === 'Stop'
         ? { systemMessage: context }
         : { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: context } }, lookup, env);
+    await sweepPrivilegedPending(typeof input.cwd === 'string' ? input.cwd : process.cwd(), env, deliveryAdapters).catch(() => undefined);
+    return response;
 }
 export async function runCodexHook(inputText, env = process.env) {
     let input;

package/dist/codex-queue.js

@@ -36,7 +36,7 @@ export class CodexQueueAdapter {
     async dispatch(address, payload, beforeSend) {
         const threadId = address.threadId?.trim();
         if (!threadId) {
-            return { outcome: 'unavailable', signature: 'invalid_address', message: 'Codex route has no thread id.' };
+            return { outcome: 'unavailable', signature: 'invalid_address', message: 'Codex route has no thread id.', routeStale: true };
         }
         const env = this.opts.env ?? process.env;
         if (!await codexQueueEligible(threadId, env)) {

package/dist/delivery-operations.js

@@ -1,11 +1,21 @@
 import { randomUUID } from 'node:crypto';
 import { formatActivityId, parseActivityId } from './square-core.js';
+import { nameKey } from './model.js';
 import { deriveDeliveryModel } from './delivery.js';
 import { isWakeRouteAttemptable } from './square-projections.js';
+import { retireWakeRouteFromArtifact } from './routes.js';
 export async function observeSquare(input) {
     const snapshot = await input.artifact.read();
     const delivery = deriveDeliveryModel(snapshot.state);
-    const rows = input.hostLedger === undefined ? [] : await input.hostLedger.listPresence({ location: input.location, scopes: ['user', 'local'], now: input.now });
+    let rows = [];
+    if (input.hostLedger !== undefined) {
+        try {
+            rows = await input.hostLedger.listPresence({ location: input.location, scopes: ['user', 'local'], now: input.now });
+        }
+        catch {
+            rows = [];
+        }
+    }
     const bindings = rows.map((record) => ({
         location: record.location,
         participant: record.participant,
@@ -21,40 +31,94 @@ export async function reconcileBinding(input) {
 }
 export async function deliverPending(input) {
     const observation = await observeSquare({ artifact: input.artifact, hostLedger: input.hostLedger, location: input.location, now: input.now });
-    const routes = (await input.hostLedger.listPresence({ location: input.location, scopes: ['user'], now: input.now })).filter((binding) => binding.route !== undefined);
+    const routes = (observation.state.routes ?? []).map((route) => ({
+        location: route.location,
+        participant: route.participant,
+        session: route.sessionId,
+        channel: route.channel,
+        route: { kind: route.kind, address: route.address },
+        updatedAt: route.updatedAt,
+    }));
     let attempted = 0;
     let accepted = 0;
     let failed = 0;
     let unknown = 0;
+    let notCapable = 0;
     for (const membership of observation.pending) {
         for (const notification of membership.notifications) {
-            const candidates = routes.filter((route) => route.participant.toLocaleLowerCase() === membership.recipient.toLocaleLowerCase());
+            const candidates = routes.filter((route) => nameKey(route.participant) === nameKey(membership.recipient));
+            if (candidates.length === 0) {
+                notCapable += 1;
+                continue;
+            }
             if (input.activity !== undefined) {
                 const requested = typeof input.activity === 'number' ? input.activity : parseActivityId(input.activity);
                 if (requested === undefined || requested !== notification.item.index)
                     continue;
             }
+            let acceptedForAttention = false;
+            try {
+                const prior = await input.hostLedger.listWakeAttempts({ attention: { squarePath: input.location, actIndex: notification.item.index, recipient: membership.recipient }, now: input.now });
+                acceptedForAttention = prior.some((attempt) => attempt.outcome === 'accepted');
+            }
+            catch { /* capability is handled by the route-level probe */ }
+            if (acceptedForAttention)
+                continue;
             for (const route of candidates) {
                 const activity = formatActivityId(notification.item.index);
                 const attention = { squarePath: input.location, actIndex: notification.item.index, recipient: membership.recipient };
                 const leaseMs = input.timeoutMs ?? 5000;
+                const requestRoute = { location: route.location, participant: route.participant, sessionId: route.session, channel: route.channel, kind: route.route.kind, address: { ...route.route.address }, updatedAt: route.updatedAt ?? 0 };
+                if (input.transport.probe !== undefined) {
+                    try {
+                        const probe = await input.transport.probe(requestRoute);
+                        if (probe === false || (typeof probe === 'object' && probe.outcome === 'not-capable')) {
+                            notCapable += 1;
+                            continue;
+                        }
+                    }
+                    catch {
+                        notCapable += 1;
+                        continue;
+                    }
+                }
                 let leaseId = randomUUID();
-                let lease = await input.hostLedger.claimWakeDispatch({ attention, leaseId, leaseMs, session: route.session, at: input.now });
+                let lease;
+                try {
+                    lease = await input.hostLedger.claimWakeDispatch({ attention, leaseId, leaseMs, session: route.session, at: input.now });
+                }
+                catch {
+                    notCapable += 1;
+                    continue;
+                }
                 if (lease.type === 'ambiguous') {
                     await input.hostLedger.appendEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', outcome: 'unknown', routeKind: lease.lease.routeKind ?? route.route.kind, attemptN: lease.lease.attemptN ?? 1, signature: 'worker_interrupted_during_dispatch', message: 'The notification worker ended after dispatch began; transport acceptance is unknown.', at: input.now });
                     await input.hostLedger.releaseWakeDispatch({ attention, leaseId: lease.lease.leaseId, session: route.session, at: input.now });
-                    leaseId = randomUUID();
-                    lease = await input.hostLedger.claimWakeDispatch({ attention, leaseId, leaseMs, session: route.session, at: input.now });
+                    continue;
                 }
                 if (lease.type !== 'acquired')
                     continue;
-                const attempts = await input.hostLedger.listWakeAttempts({ attention, session: route.session, now: input.now });
+                let attempts;
+                try {
+                    attempts = await input.hostLedger.listWakeAttempts({ attention, session: route.session, now: input.now });
+                }
+                catch {
+                    notCapable += 1;
+                    await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session, at: input.now }).catch(() => undefined);
+                    continue;
+                }
+                if (attempts.some((attempt) => attempt.routeKind === route.route.kind && attempt.outcome === 'unknown')) {
+                    await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session, at: input.now });
+                    continue;
+                }
                 const attemptN = attempts.reduce((highest, record) => Math.max(highest, record.attemptN ?? 0), 0) + 1;
-                const request = { location: input.location, participant: membership.recipient, activity, route: { location: route.location, participant: route.participant, sessionId: route.session, channel: route.channel, kind: route.route.kind, address: { ...route.route.address }, updatedAt: route.updatedAt ?? 0 } };
+                const request = { location: input.location, participant: membership.recipient, activity, route: requestRoute };
                 let outcome;
                 const claim = await input.hostLedger.claimEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', leaseMs, now: input.now });
                 if (claim.status !== 'acquired') {
                     await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session, at: input.now });
+                    if (claim.status === 'degraded')
+                        notCapable += 1;
                     continue;
                 }
                 attempted += 1;
@@ -69,8 +133,15 @@ export async function deliverPending(input) {
                 catch (error) {
                     outcome = { outcome: 'unknown', diagnostic: error instanceof Error ? error.message : String(error) };
                 }
+                if (outcome.outcome === 'not-capable') {
+                    await input.hostLedger.releaseEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', now: input.now }).catch(() => undefined);
+                    await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session, at: input.now }).catch(() => undefined);
+                    notCapable += 1;
+                    continue;
+                }
                 if (outcome.outcome === 'failed' && outcome.unavailable) {
-                    await input.transport.invalidate?.(request);
+                    if (outcome.routeStale === true)
+                        await retireWakeRouteFromArtifact(input.artifact, { location: route.location, participant: route.participant, sessionId: route.session });
                     await input.hostLedger.releaseEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', now: input.now });
                     await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session, at: input.now });
                     failed += 1;
@@ -78,16 +149,19 @@ export async function deliverPending(input) {
                 }
                 await input.hostLedger.appendEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', outcome: outcome.outcome, routeKind: route.route.kind, attemptN: outcome.attemptN ?? attemptN, ...(outcome.outcome === 'accepted' && outcome.signature === undefined ? {} : outcome.outcome === 'accepted' ? { signature: outcome.signature } : outcome.outcome === 'failed' ? { message: outcome.message } : { diagnostic: outcome.diagnostic }), at: input.now });
                 await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session, at: input.now });
-                if (outcome.outcome === 'accepted')
+                if (outcome.outcome === 'accepted') {
                     accepted += 1;
-                else if (outcome.outcome === 'failed')
+                    acceptedForAttention = true;
+                    break;
+                }
+                if (outcome.outcome === 'failed')
                     failed += 1;
                 else
                     unknown += 1;
             }
         }
     }
-    return { attempted, accepted, failed, unknown };
+    return { attempted, accepted, failed, unknown, notCapable };
 }
 export function selectPendingWakeActivities(state, routes, attempts, now, graceMs, limit, delivery = deriveDeliveryModel(state)) {
     const selected = new Set();
@@ -95,10 +169,12 @@ export function selectPendingWakeActivities(state, routes, attempts, now, graceM
         for (const notification of delivery.pendingFor(membership)) {
             if (now - notification.item.at <= graceMs)
                 continue;
+            if (attempts.some((attempt) => attempt.attention.actIndex === notification.item.index && nameKey(attempt.attention.recipient) === nameKey(membership) && attempt.outcome === 'accepted'))
+                continue;
             const eligible = routes.some((binding) => {
-                if (binding.route === undefined || binding.participant.toLocaleLowerCase() !== membership.toLocaleLowerCase())
+                if (binding.route === undefined || nameKey(binding.participant) !== nameKey(membership))
                     return false;
-                const matching = attempts.filter((attempt) => attempt.session === binding.session && attempt.attention.squarePath === binding.location && attempt.attention.recipient.toLocaleLowerCase() === membership.toLocaleLowerCase() && attempt.attention.actIndex === notification.item.index);
+                const matching = attempts.filter((attempt) => attempt.session === binding.session && nameKey(attempt.attention.recipient) === nameKey(membership) && attempt.attention.actIndex === notification.item.index);
                 return isWakeRouteAttemptable({ kind: binding.route.kind, updatedAt: binding.updatedAt ?? 0 }, matching);
             });
             if (eligible)
@@ -112,7 +188,14 @@ export async function sweepPending(input) {
     return sweepPendingFromState({ ...input, state });
 }
 export async function sweepPendingFromState(input) {
-    const [bindings, records] = await Promise.all([input.hostLedger.listPresence({ location: input.location, scopes: ['user'], now: input.now }), input.hostLedger.listWakeAttempts({ now: input.now })]);
+    const bindings = (input.state.routes ?? []).map((route) => ({ location: input.location, participant: route.participant, session: route.sessionId, channel: route.channel, route: { kind: route.kind, address: route.address }, updatedAt: route.updatedAt }));
+    let records = [];
+    try {
+        records = await input.hostLedger.listWakeAttempts({ now: input.now });
+    }
+    catch {
+        records = [];
+    }
     const attempts = records.flatMap((record) => {
         const index = parseActivityId(record.activity);
         if (index === undefined || record.routeKind === undefined || typeof record.attemptN !== 'number')

package/dist/delivery.d.ts

@@ -35,6 +35,7 @@ export type WakeDispatchResult = {
     message: string;
     diagnostic?: unknown;
     retainRoute?: boolean;
+    routeStale?: boolean;
 } | {
     outcome: 'cancelled';
 };

package/dist/host-ledger-file-adapter.js

@@ -116,7 +116,7 @@ export class FileHostLedgerPort {
     catch (error) {
         return { status: 'degraded', error };
     } }
-    async releaseEvidence(i) { const f = this.file('user', 'evidence'), location = await canon(i.location), at = i.now ?? this.clock(); await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, at)).filter(x => !(x.kind === i.kind && x.location === location && nameKey(x.participant) === nameKey(i.participant) && x.activity === i.activity && x.session === i.session && x.outcome === 'dispatching')))); }
+    async releaseEvidence(i) { const f = this.file('user', 'evidence'), location = await canon(i.location), at = i.now ?? this.clock(); await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, at, true)).filter(x => !(x.kind === i.kind && x.location === location && nameKey(x.participant) === nameKey(i.participant) && x.activity === i.activity && x.session === i.session && x.outcome === 'dispatching')))); }
     async appendEvidence(i) { const f = this.file('user', 'evidence'), r = { ...i, location: await canon(i.location), at: i.at ?? this.clock(), v: 1 }; await withFileLock(f + '.lock', LOCK, async () => { const all = await read(f, r.at, true); const base = all.filter(x => k(x) === k(r)); const replaceable = new Set(base.filter(x => x.outcome === 'dispatching' || (r.attemptN !== undefined && x.attemptN === r.attemptN)).map(x => evidenceKey(x))); await write(f, [...all.filter(x => !(x.outcome === 'dispatching' && k(x) === k(r)) && !replaceable.has(evidenceKey(x))), r]); }); }
     async listEvidence(i = {}) { const loc = i.location === undefined ? undefined : await canon(i.location); return (await read(this.file('user', 'evidence'), i.now ?? this.clock())).filter(r => (!loc || r.location === loc) && (!i.participant || nameKey(r.participant) === nameKey(i.participant)) && (!i.session || r.session === i.session) && (!i.activity || r.activity === i.activity) && (!i.kind || r.kind === i.kind)); }
     async gcEvidence(i) { const f = this.file('user', 'evidence'); await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, this.clock())).filter(r => r.at >= i.before))); }
@@ -135,21 +135,12 @@ export class FileHostLedgerPort {
         }
         const latest = new Map();
         for (const x of b) {
-            const key = JSON.stringify([x.location, nameKey(x.participant)]);
+            const key = JSON.stringify([x.location, nameKey(x.participant), x.session]);
             const current = latest.get(key);
             if (current === undefined || ((x.updatedAt ?? 0) > (current.updatedAt ?? 0)))
                 latest.set(key, x);
         }
         const winners = [...latest.values()];
-        for (const x of b) {
-            const winner = latest.get(JSON.stringify([x.location, nameKey(x.participant)]));
-            if (winner === undefined || winner.session === x.session)
-                continue;
-            for (const scope of i.scopes ?? this.readable) {
-                const remover = new FileHostLedgerPort({ userPath: this.user, localPath: this.local, writableScope: scope, readableScopes: [scope], now: this.clock });
-                await remover.removePresence(x);
-            }
-        }
         const u = new FileHostLedgerPort({ userPath: this.user, localPath: this.local, writableScope: 'user', readableScopes: ['user'], now: this.clock });
         for (const x of winners) {
             const result = await u.ensurePresence(x);

package/dist/model.d.ts

@@ -13,6 +13,8 @@ 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 {
@@ -82,6 +84,7 @@ export interface SquareState {
     preamble: string[];
     warmup: string[];
     acts: StoredAct[];
+    routes?: ReceiverRoute[];
     runtime: SquareRuntimeState;
 }
 export interface ActivitiesOptions {

package/dist/model.js

@@ -40,7 +40,7 @@ export function findParticipantName(participants, name) {
     return participants.find((participant) => sameName(participant, name));
 }
 export function validateName(name) {
-    if (!name || !/^[\p{L}\p{N}_-]+(?:\/[\p{L}\p{N}_-]+)*$/u.test(name)) {
-        throw new SquareError('invalid_name', 'Invalid name: names must contain non-empty slash-separated segments using only Unicode letters, digits, hyphens, and underscores.');
+    if (!name || !/^(?:[[\p{L}\p{N}\p{M}_\x2D]--[\p{Variation_Selector}]]|\p{RGI_Emoji})+(?:\/(?:[[\p{L}\p{N}\p{M}_\x2D]--[\p{Variation_Selector}]]|\p{RGI_Emoji})+)*$/v.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/notifications.d.ts

@@ -2,6 +2,7 @@ import { planActNotifications, type WakeAdapter } from './delivery.js';
 import { type SquareState } from './model.js';
 import { matchesMentionTarget } from './runtime.js';
 import { type ActivityId } from './square-core.js';
+import type { WakeTransportPort } from './ports.js';
 export type { PlannedNotification } from './delivery.js';
 export { planActNotifications, matchesMentionTarget };
 export { notificationMessageId } from './delivery.js';
@@ -16,7 +17,12 @@ interface ProcessNotificationOptions {
     env?: NodeJS.ProcessEnv;
     now?: () => number;
 }
+export declare function defaultWakeAdapters(): Promise<WakeAdapter[]>;
+export declare function createDefaultWakeTransport(hostLedger: import('./host-ledger.js').HostLedgerPort, clock: () => number, env?: NodeJS.ProcessEnv): Promise<WakeTransportPort>;
+export declare function createWakeTransport(adapters: readonly WakeAdapter[], hostLedger: import('./host-ledger.js').HostLedgerPort, clock: () => number): WakeTransportPort;
 export declare function processActNotificationsOnce(squarePath: string, actIndex: number, opts?: ProcessNotificationOptions): Promise<import("./ports.js").DeliveryResult>;
+/** Privileged hook fallback: sweep indexed squares plus the current cwd's local squares. */
+export declare function sweepPrivilegedPending(cwd: string, env?: NodeJS.ProcessEnv, suppliedAdapters?: WakeAdapter[]): Promise<void>;
 export interface SweepPendingNotificationsOptions {
     env?: NodeJS.ProcessEnv;
     now?: number;

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';
@@ -77,7 +78,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,12 +96,30 @@ 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 {
+        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);
                 if (result.outcome === 'accepted')
@@ -108,7 +127,7 @@ function createWakeTransport(adapters, hostLedger, clock) {
                 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 +136,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 +150,55 @@ 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. */
+export async function sweepPrivilegedPending(cwd, env = process.env, suppliedAdapters) {
+    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 */ }
+    const adapters = suppliedAdapters ?? await defaultWakeAdapters();
+    for (const squarePath of paths) {
+        try {
+            const square = await openSquare(squarePath, { hostLedger, env });
+            try {
+                const snapshot = await square.artifact.read();
+                await hostLedger.reconcileBinding({ artifact: square.artifact, scopes: ['user'], now: Date.now() }).catch(() => undefined);
+                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)
+                    await deliverPending({ artifact: square.artifact, hostLedger, transport, location: squarePath, activity: actIndex, timeoutMs: Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000), 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.js

@@ -37,6 +37,7 @@ export class PaseoAdapter {
                 outcome: 'unavailable',
                 signature: 'invalid_address',
                 message: 'Paseo route has no agent id.',
+                routeStale: true,
                 diagnostic: diagnostic('selection', address, 'invalid_address'),
             };
         }
@@ -58,6 +59,7 @@ 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))) {

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;

package/dist/square-file-adapter.js

@@ -39,6 +39,7 @@ export async function openSquare(squarePath, options = {}) {
                 userPath: env.SQUARE_HOST_LEDGER_USER ?? ledgerRoot,
                 localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? ledgerRoot,
             }),
+            wakeTransport: options.wakeTransport,
         };
     }
     catch (error) {
@@ -77,7 +78,7 @@ export function buildMemorySquare(options) {
         hardCap: options.hardCap ?? null,
         ...(options.throttlePerMinute === undefined ? {} : { throttlePerMinute: options.throttlePerMinute }),
     }, options.markdown);
-    return { artifact: memoryArtifact(createMemoryCell(squareState)), clock: options.clock ?? Date.now, location: 'memory', hostLedger: options.hostLedger };
+    return { artifact: memoryArtifact(createMemoryCell(squareState)), clock: options.clock ?? Date.now, location: 'memory', hostLedger: options.hostLedger, wakeTransport: options.wakeTransport };
 }
 function memoryArtifact(cell) {
     return { read: () => cell.read(), transact: (fn) => cell.transact(fn), changed: (since, timeout) => cell.changed(since, timeout), close: () => cell.close() };

package/dist/square-projections.js

@@ -2,6 +2,7 @@ import { formatActivityId, parseActivityId } from './square-core.js';
 import { nameKey } from './model.js';
 import { deriveDeliveryModel } from './delivery.js';
 import { freshWatchLease } from './runtime.js';
+import { canonicalRouteLocation } from './routes.js';
 function bindingProjection(record) {
     return {
         location: record.location,
@@ -53,14 +54,18 @@ export function terminalWakeEvidence(attempts) { return attempts.findLast((attem
 export function isWakeRouteAttemptable(route, attempts) {
     if (terminalWakeEvidence(attempts) !== undefined)
         return false;
-    const failed = attempts.findLast((attempt) => attempt.routeKind === route.kind && attempt.outcome === 'failed');
-    return failed === undefined || route.updatedAt > failed.at;
+    if (attempts.some((attempt) => attempt.routeKind === route.kind && attempt.outcome === 'unknown'))
+        return false;
+    return true;
 }
 export function hasAttemptableWakeRoute(routes, attempts) { return routes.some((route) => isWakeRouteAttemptable(route, attempts)); }
 export async function projectWakeEvidenceFromState(input) {
+    const canonicalLocation = await canonicalRouteLocation(input.location);
     const delivery = input.delivery ?? deriveDeliveryModel(input.state);
-    const bindings = (await input.hostLedger.listPresence({ location: input.location, scopes: ['user'], now: input.now })).map(bindingProjection);
-    const wakeRecords = await input.hostLedger.listEvidence({ location: input.location, kind: 'wake', now: input.now });
+    const bindings = (input.state.routes ?? [])
+        .filter((route) => route.location === canonicalLocation || route.location === input.location)
+        .map((route) => ({ location: route.location, participant: route.participant, sessionId: route.sessionId, channel: route.channel, route: { ...route, address: { ...route.address } }, updatedAt: route.updatedAt }));
+    const wakeRecords = await input.hostLedger.listEvidence({ location: canonicalLocation, kind: 'wake', now: input.now });
     const attemptsByBinding = new Map();
     for (const record of wakeRecords) {
         const actIndex = parseActivityId(record.activity);
@@ -72,7 +77,7 @@ export async function projectWakeEvidenceFromState(input) {
         existing.push(attempt);
         attemptsByBinding.set(key, existing);
     }
-    const presentedRows = await projectPresentationEvidence({ hostLedger: input.hostLedger, location: input.location, now: input.now });
+    const presentedRows = await projectPresentationEvidence({ hostLedger: input.hostLedger, location: canonicalLocation, now: input.now });
     return {
         evidence(recipient, actIndex) {
             const recipientBindings = bindings.filter((binding) => nameKey(binding.participant) === nameKey(recipient));

package/dist/wake-port.js

@@ -14,7 +14,7 @@ export class WakePort {
             if (result.outcome === 'cancelled')
                 return result;
             if (result.outcome === 'unavailable') {
-                if (result.retainRoute !== true)
+                if (result.routeStale === true)
                     await hooks.invalidate?.(route, result);
                 continue;
             }

package/package.json

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