@astrosheep/square 0.3.63 → 0.3.65

package/dist/packages/agent-delivery/src/pi.js

@@ -0,0 +1,209 @@
+import { createServer } from 'node:net';
+import { randomBytes } from 'node:crypto';
+import { chmod, link, lstat, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { sendPiMessage } from './pi-send.js';
+import { CUSTOM_TYPE, FRAME_WAIT_MS, MAX_CONNECTIONS, MAX_TEXT_BYTES, VERSION, endpointValid, frame, identity, readFrame, record, waitValid } from './pi-protocol.js';
+export { sendPiMessage } from './pi-send.js';
+/**
+ * Resources start only on session_start. Missing endpoint leaves the extension inert.
+ * SDK hosts that dispose without session_shutdown must explicitly close this receiver.
+ */
+export function createPiReceiver(pi, options = {}) {
+    let live;
+    let lifecycle = Promise.resolve();
+    const serialize = (work) => {
+        const result = lifecycle.then(work);
+        lifecycle = result.catch(() => { });
+        return result;
+    };
+    const retire = () => {
+        const old = live;
+        live = undefined;
+        if (old !== undefined) {
+            old.retired = true;
+            for (const waiter of [...old.waiters.values()])
+                waiter.finish('unknown', 'session_replaced');
+            for (const socket of old.sockets)
+                socket.destroy();
+        }
+        return old;
+    };
+    const stop = async (old) => {
+        if (old === undefined)
+            return;
+        if (old.published !== undefined) {
+            const own = old.published;
+            old.published = undefined;
+            const current = await lstat(old.endpoint).catch(() => undefined);
+            if (current?.isSocket() && current.dev === own.dev && current.ino === own.ino)
+                await unlink(old.endpoint);
+        }
+        // Bind under an owned temporary name: Node blindly unlinks its bind path on close.
+        // Publishing a hard link lets us protect a replacement at the caller's explicit endpoint.
+        if (old.server?.listening)
+            await new Promise((resolve) => old.server.close(() => resolve()));
+    };
+    const close = () => {
+        const old = retire();
+        return serialize(() => stop(old));
+    };
+    pi.on('session_start', async (_event, ctx) => {
+        // Getter is deliberately read here, after Pi applies extension flag values.
+        const endpoint = options.endpoint;
+        const sessionId = ctx.sessionManager.getSessionId();
+        if (live !== undefined && !live.retired && live.sessionId === sessionId &&
+            live.endpoint === endpoint && live.manager === ctx.sessionManager)
+            return lifecycle;
+        const old = retire();
+        const state = endpoint === undefined ? undefined : {
+            sessionId, endpoint, manager: ctx.sessionManager, sockets: new Set(), waiters: new Map(), retired: false,
+        };
+        live = state;
+        return serialize(async () => {
+            await stop(old);
+            if (state === undefined || state.retired)
+                return;
+            try {
+                if (process.platform !== 'darwin')
+                    throw new Error('Pi delivery requires macOS.');
+                if (!endpointValid(state.endpoint) || !identity(state.sessionId))
+                    throw new Error('Invalid Pi receiver coordinate.');
+                const parent = await lstat(dirname(state.endpoint));
+                if (!parent.isDirectory() || parent.uid !== process.getuid?.() || (parent.mode & 0o077) !== 0) {
+                    throw new Error('Pi delivery requires a private caller-owned parent directory.');
+                }
+                // Fail closed even for stale sockets/files. No reclaim or broad chmod.
+                try {
+                    await lstat(state.endpoint);
+                    throw new Error('Pi delivery endpoint is occupied.');
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+                if (state.retired)
+                    return;
+                const bindPath = join(dirname(state.endpoint), `.pi-${randomBytes(6).toString('hex')}`);
+                if (!endpointValid(bindPath))
+                    throw new Error('Invalid Pi receiver coordinate.');
+                const server = createServer((socket) => accept(state, socket));
+                state.server = server;
+                // All diagnostics are fixed text: no path, request, or native error cause.
+                server.on('error', () => { if (live === state)
+                    void close(); });
+                await new Promise((resolve, reject) => {
+                    server.once('error', () => reject(new Error('Pi delivery listener unavailable.')));
+                    server.listen(bindPath, resolve);
+                });
+                if (state.retired) {
+                    await stop(state);
+                    return;
+                }
+                await chmod(bindPath, 0o600);
+                const owned = await lstat(bindPath);
+                await link(bindPath, state.endpoint); // Atomic no-replace publish; even a race fails closed.
+                state.published = { dev: owned.dev, ino: owned.ino };
+                if (state.retired)
+                    await stop(state);
+            }
+            catch {
+                if (live === state)
+                    retire();
+                await stop(state);
+                throw new Error('Pi delivery listener unavailable.');
+            }
+        });
+    });
+    function accept(state, socket) {
+        if (state.retired || state.sockets.size >= MAX_CONNECTIONS) {
+            socket.destroy();
+            return;
+        }
+        state.sockets.add(socket);
+        socket.on('error', () => { });
+        let waiter;
+        let timer = setTimeout(() => socket.destroy(), FRAME_WAIT_MS);
+        const reply = (value) => {
+            if (!socket.destroyed)
+                socket.end(frame(value));
+            // A non-reading peer must not retain the connection after an attempted reply.
+            clearTimeout(timer);
+            timer = setTimeout(() => socket.destroy(), FRAME_WAIT_MS);
+        };
+        const reject = (code) => reply({ protocol: VERSION, state: 'rejected', code });
+        const detach = readFrame(socket, (request) => {
+            clearTimeout(timer);
+            if (!record(request) || request.protocol !== VERSION || request.harness !== 'pi') {
+                reject('invalid_request');
+                return;
+            }
+            if (state.retired || live !== state || request.sessionId !== state.sessionId) {
+                reject('wrong_session');
+                return;
+            }
+            if (request.op === 'hello') {
+                reply({ protocol: VERSION, harness: 'pi', sessionId: state.sessionId });
+                return;
+            }
+            if (request.op !== 'send' || typeof request.text !== 'string' || request.text.length === 0 ||
+                Buffer.byteLength(request.text) > MAX_TEXT_BYTES || !identity(request.inputId) ||
+                (request.delivery !== 'steer' && request.delivery !== 'queue') || !waitValid(request.timeoutMs) ||
+                Object.keys(request).some((key) => !['protocol', 'harness', 'op', 'sessionId', 'text', 'inputId', 'delivery', 'timeoutMs'].includes(key))) {
+                reject('invalid_request');
+                return;
+            }
+            const { inputId, text, delivery, timeoutMs } = request;
+            if (state.waiters.has(inputId)) {
+                reject('duplicate_inflight_id');
+                return;
+            }
+            let settled = false;
+            waiter = {
+                text,
+                finish(result, code) {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    state.waiters.delete(inputId);
+                    reply({ protocol: VERSION, harness: 'pi', sessionId: state.sessionId, inputId, delivery,
+                        state: result, ...(result === 'observed' ? { evidence: 'message_end' } : { code }) });
+                },
+            };
+            // Register first: native events may be synchronous in an embedding.
+            state.waiters.set(inputId, waiter);
+            timer = setTimeout(() => waiter?.finish('unknown', 'timeout'), timeoutMs);
+            try {
+                sendPiMessage(pi, { customType: CUSTOM_TYPE, content: text, display: true,
+                    details: { agentDelivery: { deliveryId: inputId } } }, { deliverAs: delivery === 'queue' ? 'followUp' : 'steer', triggerTurn: true });
+            }
+            catch {
+                waiter.finish('unknown', 'native_call');
+            }
+        }, () => socket.destroy());
+        socket.once('close', () => {
+            detach();
+            waiter?.finish('unknown', 'transport');
+            clearTimeout(timer);
+            state.sockets.delete(socket);
+        });
+    }
+    pi.on('message_end', (event, ctx) => {
+        const state = live;
+        const message = event.message;
+        if (state === undefined || state.retired || ctx.sessionManager !== state.manager ||
+            ctx.sessionManager.getSessionId() !== state.sessionId || !record(message) ||
+            message.role !== 'custom' || message.customType !== CUSTOM_TYPE || !record(message.details) ||
+            !record(message.details.agentDelivery))
+            return;
+        const id = message.details.agentDelivery.deliveryId;
+        if (typeof id !== 'string')
+            return;
+        const waiter = state.waiters.get(id);
+        if (waiter !== undefined && message.content === waiter.text)
+            waiter.finish('observed');
+    });
+    pi.on('session_shutdown', close);
+    return { close };
+}

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

@@ -0,0 +1,120 @@
+declare const targetBrand: unique symbol;
+export interface OpenCodeTarget {
+    readonly harness: 'opencode';
+    readonly sessionId: string;
+    readonly [targetBrand]: true;
+}
+export interface ClaudeTarget {
+    readonly harness: 'claude';
+    readonly sessionId: string;
+    readonly [targetBrand]: true;
+}
+export interface PiTarget {
+    readonly harness: 'pi';
+    readonly sessionId: string;
+    readonly [targetBrand]: true;
+}
+export interface PaseoTarget {
+    readonly harness: 'paseo';
+    readonly agentId: string;
+    readonly [targetBrand]: true;
+}
+export type Target = OpenCodeTarget | ClaudeTarget | PiTarget | PaseoTarget;
+export type Delivery = 'steer' | 'queue';
+export interface OpenCodeSendTextOptions {
+    readonly delivery?: Delivery;
+    readonly inputId?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ClaudeSendTextOptions {
+    readonly delivery?: 'steer';
+    readonly inputId?: never;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface PiSendTextOptions {
+    readonly delivery?: Delivery;
+    readonly inputId?: never;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface PaseoSendTextOptions {
+    readonly delivery?: 'steer';
+    readonly inputId?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export type SendTextOptions = OpenCodeSendTextOptions | ClaudeSendTextOptions | PiSendTextOptions | PaseoSendTextOptions;
+interface OpenCodeAttempt {
+    readonly harness: 'opencode';
+    readonly sessionId: string;
+    readonly inputId: string;
+}
+export type OpenCodeDeliveryResult = (OpenCodeAttempt & {
+    readonly state: 'accepted';
+    readonly inboxId: string;
+    readonly delivery: Delivery;
+}) | (OpenCodeAttempt & {
+    readonly state: 'unknown';
+    readonly code: 'timeout' | 'aborted' | 'transport' | 'invalid_response';
+}) | (OpenCodeAttempt & {
+    readonly state: 'rejected';
+    readonly code: 'http_rejection';
+    readonly status: number;
+}) | (OpenCodeAttempt & {
+    readonly state: 'unavailable';
+    readonly code: 'aborted' | 'timeout';
+});
+interface ClaudeAttempt {
+    readonly harness: 'claude';
+    readonly sessionId: string;
+}
+export type ClaudeDeliveryResult = (ClaudeAttempt & {
+    readonly state: 'written';
+    readonly messageId: string;
+}) | (ClaudeAttempt & {
+    readonly state: 'unknown';
+    readonly code: 'timeout' | 'aborted' | 'transport';
+}) | (ClaudeAttempt & {
+    readonly state: 'unavailable';
+    readonly code: 'aborted' | 'timeout' | 'endpoint_unavailable' | 'authentication_failed';
+});
+interface PiAttempt {
+    readonly harness: 'pi';
+    readonly sessionId: string;
+    readonly inputId: string;
+}
+export type PiDeliveryResult = (PiAttempt & {
+    readonly state: 'observed';
+    readonly evidence: 'message_end';
+    readonly delivery: Delivery;
+}) | (PiAttempt & {
+    readonly state: 'unknown';
+    readonly code: 'timeout' | 'aborted' | 'transport' | 'invalid_response' | 'session_replaced' | 'native_call';
+}) | (PiAttempt & {
+    readonly state: 'rejected';
+    readonly code: 'wrong_session' | 'invalid_request' | 'duplicate_inflight_id';
+}) | (PiAttempt & {
+    readonly state: 'unavailable';
+    readonly code: 'timeout' | 'aborted' | 'transport' | 'invalid_response';
+});
+interface PaseoAttempt {
+    readonly harness: 'paseo';
+    readonly agentId: string;
+    readonly inputId: string;
+}
+export type PaseoDeliveryResult = (PaseoAttempt & {
+    readonly state: 'admitted';
+}) | (PaseoAttempt & {
+    readonly state: 'rejected';
+    readonly code: 'key_conflict' | 'not_found' | 'refused';
+}) | (PaseoAttempt & {
+    readonly state: 'unavailable';
+    readonly code: 'aborted' | 'timeout' | 'authentication_failed' | 'transport';
+}) | (PaseoAttempt & {
+    readonly state: 'unknown';
+    readonly code: 'timeout' | 'aborted' | 'transport';
+});
+export type DeliveryResult = OpenCodeDeliveryResult | ClaudeDeliveryResult | PiDeliveryResult | PaseoDeliveryResult;
+export {};

package/dist/participant-host.js

@@ -1,12 +1,9 @@
-import { readParticipantOwner, sessionOwnsParticipant } from './registry.js';
+import { presenceEpoch, readParticipantOwner, sessionOwnsParticipant } from './registry.js';
+import { firstHarnessSession } from './participant-identity.js';
 import { defaultWakeRouteCapabilities, publishWakeRoute, retireWakeRouteFromArtifact, resolvePrimaryWakeRoute, ROUTE_FRESH_MS } from './routes.js';
 export function processIdentity(env) {
-    const choices = [
-        [env.CLAUDE_CODE_SESSION_ID, 'claude-code'], [env.CODEX_THREAD_ID, 'codex'],
-        [env.OPENCODE_SESSION_ID, 'opencode'], [env.PI_SESSION_ID, 'pi'], [env.PASEO_AGENT_ID, 'paseo'],
-    ];
-    const found = choices.find(([session]) => session?.trim());
-    return found === undefined ? { session: `process:${process.pid}`, channel: 'unknown' } : { session: found[0].trim(), channel: found[1] };
+    const found = firstHarnessSession(env);
+    return found === undefined ? { session: `process:${process.pid}`, channel: 'unknown' } : { session: found.sessionId, channel: found.channel };
 }
 export async function identityRouteDraft(context, participant) {
     if (context.location === undefined || context.location === 'memory')
@@ -17,10 +14,11 @@ export async function identityRouteDraft(context, participant) {
     return resolvePrimaryWakeRoute({ location: context.location, participant, sessionId: identity.session, provider }, context.env ?? process.env, capabilities);
 }
 async function currentOwnerEpoch(context, participant) {
-    if (context.location === undefined || context.location === 'memory')
+    const hostLedger = context.hostLedger;
+    if (hostLedger === undefined || context.location === undefined || context.location === 'memory')
         return undefined;
-    const owner = await readParticipantOwner(context.location, participant, context.env ?? process.env);
-    return owner?.epoch;
+    const owner = await readParticipantOwner(context.location, participant, hostLedger);
+    return owner === undefined ? undefined : presenceEpoch(owner);
 }
 export async function publishIdentityRoute(context, participant, epoch) {
     const route = await identityRouteDraft(context, participant);
@@ -36,13 +34,14 @@ export async function retireIdentityRoute(context, participant, expectedEpoch) {
     await retireWakeRouteFromArtifact(context.artifact, { location: context.location, participant, sessionId: identity.session }, expectedEpoch === undefined ? {} : { expectedEpoch }).catch(() => undefined);
 }
 export async function assertLiveOwner(context, participant, expectedEpoch) {
-    if (context.hostLedger === undefined || context.location === undefined || context.location === 'memory')
+    const hostLedger = context.hostLedger;
+    if (hostLedger === undefined || context.location === undefined || context.location === 'memory')
         return true;
     const identity = processIdentity(context.env ?? process.env);
     // Library callers without a harness session are not ownership-fenced unless an epoch was supplied.
     if (identity.channel === 'unknown' && expectedEpoch === undefined)
         return true;
-    return sessionOwnsParticipant(context.location, participant, identity.session, context.env ?? process.env, expectedEpoch);
+    return sessionOwnsParticipant(context.location, participant, identity.session, hostLedger, expectedEpoch);
 }
 /** Presence is best effort and runs only after the artifact mutation commits. */
 export async function ensureLocalPresence(context, participant, epoch) {
@@ -56,7 +55,7 @@ export async function ensureLocalPresence(context, participant, epoch) {
         const existing = await context.hostLedger.listPresence({ location: context.location, participant, session: identity.session, now });
         if (existing.some((row) => row.channel === identity.channel
             && now - (row.updatedAt ?? 0) < ROUTE_FRESH_MS
-            && (ownerEpoch === undefined || row.epoch === ownerEpoch)))
+            && (ownerEpoch === undefined || presenceEpoch(row) === ownerEpoch)))
             return;
     }
     catch { /* fall through to the best-effort ensure below */ }

package/dist/participant-identity.d.ts

@@ -1,5 +1,26 @@
 export declare function participantIdentity(name: string): string;
 export type AutomaticProvider = 'codex' | 'claude' | 'opencode' | 'pi';
+/** Channels a harness coordinate can map to. `unknown` stays a process-level fallback, not a coordinate. */
+export type HarnessSessionChannel = 'claude-code' | 'codex' | 'opencode' | 'pi' | 'paseo';
+export type HarnessSessionVariable = 'CLAUDE_CODE_SESSION_ID' | 'CODEX_THREAD_ID' | 'OPENCODE_SESSION_ID' | 'PI_SESSION_ID' | 'PASEO_AGENT_ID';
+/**
+ * Ordered harness environment coordinates. This one table is the mapping owner every consumer
+ * derives from; `provider` is absent for a coordinate without an automatic participant provider.
+ */
+export interface HarnessSessionSource {
+    readonly variable: HarnessSessionVariable;
+    readonly channel: HarnessSessionChannel;
+    readonly provider?: AutomaticProvider;
+    readonly childVariable?: 'CLAUDE_CODE_CHILD_SESSION';
+}
+export declare const harnessSessionSources: readonly HarnessSessionSource[];
+/** Raw nonempty harness session ids in table order. Duplicates are preserved, never collapsed. */
+export declare function sessionIdsFromEnvironment(env?: NodeJS.ProcessEnv): readonly string[];
+/** The first nonempty harness coordinate in table order, or undefined when none is set. */
+export declare function firstHarnessSession(env?: NodeJS.ProcessEnv): {
+    readonly sessionId: string;
+    readonly channel: HarnessSessionChannel;
+} | undefined;
 export declare function automaticParticipant(provider: AutomaticProvider, sessionId: string, env: NodeJS.ProcessEnv): string;
 /** Compute the current harness participant without reading a Square or registry artifact. */
 export declare function squareAssignedParticipantName(env?: NodeJS.ProcessEnv): string | undefined;

package/dist/participant-identity.js

@@ -3,12 +3,28 @@ import { validateName } from './model.js';
 export function participantIdentity(name) {
     return `@${name}`;
 }
-const nativeSessions = [
-    { variable: 'CLAUDE_CODE_SESSION_ID', provider: 'claude' },
-    { variable: 'CODEX_THREAD_ID', provider: 'codex' },
-    { variable: 'OPENCODE_SESSION_ID', provider: 'opencode' },
-    { variable: 'PI_SESSION_ID', provider: 'pi' },
+export const harnessSessionSources = [
+    { variable: 'CLAUDE_CODE_SESSION_ID', channel: 'claude-code', provider: 'claude', childVariable: 'CLAUDE_CODE_CHILD_SESSION' },
+    { variable: 'CODEX_THREAD_ID', channel: 'codex', provider: 'codex' },
+    { variable: 'OPENCODE_SESSION_ID', channel: 'opencode', provider: 'opencode' },
+    { variable: 'PI_SESSION_ID', channel: 'pi', provider: 'pi' },
+    { variable: 'PASEO_AGENT_ID', channel: 'paseo' },
 ];
+/** Raw nonempty harness session ids in table order. Duplicates are preserved, never collapsed. */
+export function sessionIdsFromEnvironment(env = process.env) {
+    return harnessSessionSources
+        .map((source) => env[source.variable]?.trim())
+        .filter((value) => Boolean(value));
+}
+/** The first nonempty harness coordinate in table order, or undefined when none is set. */
+export function firstHarnessSession(env = process.env) {
+    for (const source of harnessSessionSources) {
+        const sessionId = env[source.variable]?.trim();
+        if (sessionId)
+            return { sessionId, channel: source.channel };
+    }
+    return undefined;
+}
 export function automaticParticipant(provider, sessionId, env) {
     const configured = env.SQUARE_PARTICIPANT_NAME?.trim();
     if (configured) {
@@ -25,11 +41,16 @@ export function squareAssignedParticipantName(env = process.env) {
         validateName(configured);
         return configured;
     }
-    const names = new Set(nativeSessions
-        .map(({ variable, provider }) => {
-        const sessionId = env[variable]?.trim();
-        return sessionId === undefined || sessionId === '' ? undefined : automaticParticipant(provider, sessionId, env);
-    })
-        .filter((name) => name !== undefined));
+    // Every native provider contributes its own name without deduping session ids first: equal ids
+    // in different providers are different coordinates and must stay ambiguous.
+    const names = new Set();
+    for (const source of harnessSessionSources) {
+        if (source.provider === undefined)
+            continue;
+        const sessionId = env[source.variable]?.trim();
+        if (!sessionId)
+            continue;
+        names.add(automaticParticipant(source.provider, sessionId, env));
+    }
     return names.size === 1 ? [...names][0] : undefined;
 }

package/dist/paseo-delivery.d.ts

@@ -1,4 +1,4 @@
-import { type WakeAdapter, type WakeDispatchResult } from './delivery.js';
+import { type WakeAdapter, type WakeAdapterResult, type WakeDispatchContext } from './delivery.js';
 import { discoverPaseoAgents, waitForPaseoWakeBoundary } from './paseo-state.js';
 import { sendPaseoWake } from './wake-sink.js';
 export interface PaseoAdapterOptions {
@@ -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>, timeoutMs?: number): Promise<WakeDispatchResult>;
+    dispatch(address: Readonly<Record<string, string>>, payload: string, beforeSend: () => Promise<boolean>, timeoutMs?: number, context?: WakeDispatchContext): Promise<WakeAdapterResult>;
 }

package/dist/paseo-delivery.js

@@ -1,40 +1,31 @@
-import { paseoDaemonHosts, resolvePaseoDaemonTarget } from './paseo-connection.js';
+import { DeliveryError } from './packages/agent-delivery/src/index.js';
+import { resolvePaseoDaemon } from './packages/agent-delivery/src/paseo-native.js';
 import { discoverPaseoAgents, waitForPaseoWakeBoundary } from './paseo-state.js';
-import { PaseoWakeSendError, sendPaseoWake } from './wake-sink.js';
-function endpoint() {
-    try {
-        return resolvePaseoDaemonTarget(paseoDaemonHosts()[0]).url;
-    }
-    catch {
-        return 'unresolved';
-    }
-}
+import { sendPaseoWake } from './wake-sink.js';
+/** Every send failure is a DeliveryError; only its code and certainty decide retry. */
 function diagnostic(phase, address, code) {
     return {
         phase,
         code,
-        command: phase === 'discovery' ? 'paseo ls --global --json' : 'paseo send <agent-id> --prompt <prompt> --no-wait --json',
-        endpoint: endpoint(),
+        // Only discovery still runs a Paseo CLI; a wake is a capability call on the shared entry.
+        ...(phase === 'discovery' ? { command: 'paseo ls --global --json' } : {}),
+        endpoint: resolvePaseoDaemon(undefined)?.url ?? 'unresolved',
         paseoAgentIds: [address.agentId].filter(Boolean),
         passwordPresent: Boolean(process.env.PASEO_PASSWORD),
     };
 }
-function discoveryRetryable(message) {
-    if (/password|auth|unauthori[sz]ed/i.test(message))
-        return false;
-    return /DAEMON_NOT_RUNNING|ECONNREFUSED|ENOENT|not found.*executable|ETIMEDOUT|timed out|timeout/i.test(message);
-}
 export class PaseoAdapter {
     opts;
     kind = 'paseo';
     constructor(opts = {}) {
         this.opts = opts;
     }
-    async dispatch(address, payload, beforeSend, timeoutMs = 5000) {
+    async dispatch(address, payload, beforeSend, timeoutMs = 5000, context) {
         const deadline = Date.now() + timeoutMs;
         const remainingMs = () => Math.max(0, deadline - Date.now());
         const budgetUnavailable = () => ({
-            outcome: 'unavailable',
+            outcome: 'failed',
+            unavailable: true,
             signature: 'dispatch_budget_exhausted',
             message: 'The wake dispatch budget elapsed before Paseo accepted the wake.',
             retainRoute: true,
@@ -42,7 +33,8 @@ export class PaseoAdapter {
         const agentId = address.agentId?.trim();
         if (!agentId) {
             return {
-                outcome: 'unavailable',
+                outcome: 'failed',
+                unavailable: true,
                 signature: 'invalid_address',
                 message: 'Paseo route has no agent id.',
                 routeStale: true,
@@ -55,8 +47,12 @@ export class PaseoAdapter {
         const discovery = (this.opts.discover ?? discoverPaseoAgents)(remaining);
         if (discovery.error && discovery.agents.length === 0) {
             return {
-                outcome: 'unavailable',
-                signature: discoveryRetryable(discovery.error) ? 'discovery_transient' : 'discovery_rejected',
+                outcome: 'failed',
+                unavailable: true,
+                // A credential or authorization refusal is proven; anything else may be transient.
+                signature: /password|auth|unauthori[sz]ed/i.test(discovery.error) ? 'discovery_rejected'
+                    : /DAEMON_NOT_RUNNING|ECONNREFUSED|ENOENT|not found.*executable|ETIMEDOUT|timed out|timeout/i.test(discovery.error)
+                        ? 'discovery_transient' : 'discovery_rejected',
                 message: `Paseo unavailable: ${discovery.error}`,
                 diagnostic: diagnostic('discovery', address, 'unavailable'),
                 retainRoute: true,
@@ -65,7 +61,8 @@ export class PaseoAdapter {
         const agent = discovery.agents.find((candidate) => candidate.id === agentId);
         if (agent === undefined || agent.status !== 'idle') {
             return {
-                outcome: 'unavailable',
+                outcome: 'failed',
+                unavailable: true,
                 signature: agent === undefined ? 'address_not_found' : 'agent_not_idle',
                 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'),
@@ -78,7 +75,8 @@ export class PaseoAdapter {
             return budgetUnavailable();
         if (!(await (this.opts.waitForBoundary ?? waitForPaseoWakeBoundary)(agent, remaining))) {
             return {
-                outcome: 'unavailable',
+                outcome: 'failed',
+                unavailable: true,
                 signature: 'boundary_unavailable',
                 message: 'Paseo did not reach the current tool boundary before the wake timeout.',
                 diagnostic: diagnostic('boundary', address, 'unavailable'),
@@ -86,17 +84,27 @@ export class PaseoAdapter {
             };
         }
         if (!(await beforeSend()))
-            return { outcome: 'cancelled' };
+            return { outcome: 'gate-rejected' };
         remaining = remainingMs();
         if (remaining === 0)
             return budgetUnavailable();
         try {
-            (this.opts.sendWake ?? sendPaseoWake)({ agentId, prompt: payload }, { timeoutMs: remaining });
+            await (this.opts.sendWake ?? sendPaseoWake)({
+                agentId,
+                prompt: payload,
+                location: context?.location ?? '',
+                participant: context?.participant ?? '',
+                activity: context?.activity ?? '',
+                ...(context?.attemptN === undefined ? {} : { attemptN: context.attemptN }),
+            }, { timeoutMs: remaining });
             return { outcome: 'accepted' };
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            const kind = error instanceof PaseoWakeSendError ? error.kind : 'unknown';
+            const kind = !(error instanceof DeliveryError) || error.maybeDelivered ? 'unknown'
+                : error.code === 'unavailable' ? 'transient'
+                    : ['authentication_failed', 'session_not_found', 'rejected', 'invalid_arguments'].includes(error.code) ? 'rejected'
+                        : 'unknown';
             const details = { ...diagnostic('send', address, 'failed'), outcome: kind };
             if (kind === 'unknown')
                 return { outcome: 'unknown', signature: 'send_unknown', message, diagnostic: details };