@nelsonlongxiang/dsh-open-a2a-net 0.6.28 → 0.6.30

package/lib/faces/wire.js

@@ -0,0 +1,669 @@
+import { isRemoteMemberRef, validRemoteMemberRef } from "../canvas-store.js";
+import { TRANSCRIPT_DEFAULT_LIMIT, TRANSCRIPT_MAX_LIMIT } from "../session-transcript.js";
+import { refuseIfBudgetExhausted } from "../recursion-guard.js";
+import { peerPayloadFingerprint, WIRE_ERROR_IDEMPOTENCY_CONFLICT, WIRE_ERROR_REPLAY_REJECTED } from "../idempotency-store.js";
+import { briefOf } from "../task-ledger.js";
+import { WIRE_ERROR_PAYLOAD_TOO_LARGE, withinRouteBodyCap } from "../transport-caps.js";
+/**
+ * Register the small wire faces on a settled web server.
+ * @param webServer - the settled host web server.
+ * @param d - the captures listed on {@link WireDeps}.
+ */
+export function registerWireFaces(webServer, d) {
+    const { ctx, logger, config, cliDeposits, canvasStore, sessionNodes, joinedSessions, idempotencyStore, verifyOriginClaim, callerLinkedToThisHost, recordActivity, secretEqual, a2aCallerRefusal, scanSessionLogList, readSessionLogTail, taskLedger, refuseIfFlooded, settleAndAnnounce, session, resolveAgentForTeam, parseCanvasTeamName, canvasLiveAgent, wakeColdTeam, probeConsumption, steerRelay, fromClause, armReceiptAutosend, receiptExpectationOf, armAsyncNudge, liveAgent, callerIsAgent, selfRouteText, noWakeFaceText, archivedColdMatchText, noColdMatchText, nativeTeamsPrepare, nativeTeamsRound, routeIntoAgent, } = d;
+    // gh#45 CLI 户口卡面 (peer face, unsigned card serve): the deposited
+    // CLI's SIGNED card is served verbatim under its own base URL — an
+    // OriginClaim verification of a CLI envelope fetches exactly here
+    // (callerUrl + /.well-known/agent-card.json). Expired or unknown
+    // handles 404 (auto-deregistered — the identity is dead until
+    // re-publish).
+    ctx.effect(() => webServer.register({
+        kind: 'prefix',
+        path: '/a2a/cli',
+        handler: (req, res) => {
+            const MOUNT = '/a2a/cli';
+            const rest = (req.url ?? '').slice(MOUNT.length);
+            const m = /^\/([^/]+)\/\.well-known\/agent-card\.json$/.exec(rest);
+            if (req.method !== 'GET' || m === null) {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end();
+                return;
+            }
+            const handle = decodeURIComponent(m[1]);
+            const row = cliDeposits.get(handle);
+            if (row === undefined) {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end();
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+            res.end(row.cardJson);
+        },
+    }), 'a2a: cli deposit card face');
+    // gh#41 fleet planning, peer-write face: a LINKED peer may regulate this
+    // host's canvas teams (create / add-member / remove-member) with a
+    // VERIFIED OriginClaim envelope. The owner's ruling: any peer composes
+    // and regulates the whole fleet — the bilateral/operator link IS the
+    // authorization, the envelope proves the key, and every op lands in the
+    // activity ring + host log for audit. Unlinked or unsigned callers get
+    // a refusal, never a mutation.
+    ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/a2a/canvas-op',
+        handler: async (req, res) => {
+            const send = (status, payload) => {
+                res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                res.end(payload);
+            };
+            if (req.method !== 'POST') {
+                send(200, JSON.stringify({ ok: false, error: 'POST required' }));
+                return;
+            }
+            const chunks = [];
+            let size = 0;
+            req.on('data', (chunk) => { size += chunk.length; if (size > 16 * 1024) {
+                chunks.length = 0;
+                return;
+            } chunks.push(chunk); });
+            req.on('end', () => {
+                void (async () => {
+                    try {
+                        const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                        const claim = await verifyOriginClaim(req);
+                        if (!claim.ok) {
+                            logger.warn(`a2a: canvas-op claim failed (${claim.reason}) — caller=${String(req.headers['x-a2a-caller'] ?? '')} url=${String(req.headers['x-a2a-caller-url'] ?? '')} ts=${String(req.headers['x-a2a-caller-ts'] ?? '')}`);
+                            send(200, JSON.stringify({ ok: false, error: `untrusted-origin: OriginClaim verification failed (${claim.reason}) — canvas regulation requires a signed envelope`, code: -32000 }));
+                            return;
+                        }
+                        if (!callerLinkedToThisHost(claim.caller, claim.callerUrl, claim.card)) {
+                            recordActivity('in', 'fleet-canvas', claim.caller, false);
+                            send(200, JSON.stringify({ ok: false, error: `caller "${claim.caller}" is not linked to this host — canvas regulation requires the operator link (bilateral seed, canvas ref, or same-host membership)` }));
+                            return;
+                        }
+                        const op = body.op;
+                        const name = typeof body.name === 'string' ? body.name : '';
+                        const id = typeof body.id === 'string' ? body.id : '';
+                        let payload;
+                        if (op === 'create') {
+                            const stored = canvasStore.create(name);
+                            payload = stored === undefined ? { ok: false, error: 'invalid name or team cap reached' } : { ok: true, members: canvasStore.membersOf(stored) };
+                        }
+                        else if (op === 'add-member') {
+                            const memberValid = isRemoteMemberRef(id) ? validRemoteMemberRef(id) : id !== '' && (sessionNodes.has(id) || joinedSessions.has(id));
+                            payload = name === '' || !memberValid
+                                ? { ok: false, error: 'name and a member (joined session id, or a zone-qualified remote team handle) are required' }
+                                : (canvasStore.create(name), { ok: canvasStore.addMember(name, id), members: canvasStore.membersOf(name) });
+                        }
+                        else if (op === 'remove-member') {
+                            payload = { ok: name !== '' && canvasStore.removeMember(name, id), members: name !== '' ? canvasStore.membersOf(name) : undefined };
+                        }
+                        else {
+                            payload = { ok: false, error: 'op must be create | add-member | remove-member' };
+                        }
+                        recordActivity('in', 'fleet-canvas', `${claim.caller}:${String(op)}`, payload.ok);
+                        logger.info(`a2a: fleet canvas op from ${claim.caller} (${String(op)} ${name}${id !== '' ? ` ${id}` : ''}) -> ${payload.ok ? 'applied' : `refused: ${payload.error ?? '?'}`}`);
+                        send(200, JSON.stringify(payload));
+                    }
+                    catch (error) {
+                        send(200, JSON.stringify({ ok: false, error: `canvas-op failed: ${error instanceof Error ? error.message : String(error)}` }));
+                    }
+                })();
+            });
+        },
+    }), 'a2a: fleet canvas-op peer route');
+    // 0.6.15: the read-only peer log face — a peer asks for THIS node's
+    // session transcript tail (or, without id, the readable-session
+    // listing) so a remote workbench can show "what has this node been
+    // talking about". Admission is a2aCallerRefusal — exactly the rule
+    // /a2a/direct applies to message delivery: caller_session required,
+    // zone/id8 callers judged on shared teams. Read semantics are the
+    // local /__dsh_a2a/session-log face verbatim (artifact existence is
+    // the only gate; archived and never-joined sessions stay readable;
+    // caps mirror session-transcript.ts). Nothing here steers a session,
+    // claims a task, or writes state — the only side effects are the
+    // activity-ring record and the admission path's background
+    // directory learn.
+    ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/a2a/log',
+        handler: async (req, res) => {
+            const send = (status, body) => {
+                const payload = JSON.stringify(body);
+                res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                res.end(payload);
+            };
+            if (req.method !== 'GET') {
+                send(405, { ok: false, error: 'GET is the only method on this face' });
+                return;
+            }
+            // V2 (gh#7, S1): the read-only log face rides the same apiKey gate
+            // as delivery — a configured key must be presented here too.
+            if (config.apiKey !== '') {
+                const presented = String(req.headers['x-api-key'] ?? '');
+                if (!secretEqual(presented, config.apiKey)) {
+                    send(401, { ok: false, error: 'unauthorized: X-API-Key required (apiKey is configured)', code: -32000 });
+                    return;
+                }
+            }
+            const url = new URL(req.url ?? '/', 'http://x');
+            const caller = url.searchParams.get('caller_session') ?? '';
+            const id = url.searchParams.get('id') ?? '';
+            const limitArg = Number(url.searchParams.get('limit') ?? TRANSCRIPT_DEFAULT_LIMIT);
+            const limit = Number.isFinite(limitArg) ? Math.max(1, Math.min(TRANSCRIPT_MAX_LIMIT, Math.floor(limitArg))) : TRANSCRIPT_DEFAULT_LIMIT;
+            const refusal = a2aCallerRefusal(caller);
+            if (refusal !== undefined) {
+                recordActivity('in', 'log', caller === '' ? 'anonymous' : caller, false);
+                send(200, { ok: false, error: refusal, code: -32000 });
+                return;
+            }
+            // gh#9+gh#10: the log face reuses the exact OriginClaim
+            // verification (§8.3) — same window semantics as delivery.
+            const logClaim = await verifyOriginClaim(req);
+            if (!logClaim.ok) {
+                if (logClaim.reason !== 'absent' || config.originClaimWindow === false) {
+                    recordActivity('in', 'log', caller, false);
+                    send(200, { ok: false, error: `untrusted-origin: OriginClaim verification failed (${logClaim.reason}) — present a signed envelope or upgrade your node`, code: -32000 });
+                    return;
+                }
+                d.bumpLegacyInbound();
+            }
+            recordActivity('in', 'log', caller, true);
+            if (id.includes('/') || id.includes('\\') || id.includes('..')) {
+                send(200, { ok: false, error: 'id is required' });
+                return;
+            }
+            if (id === '') {
+                try {
+                    const rows = scanSessionLogList();
+                    send(200, { ok: true, count: rows.length, sessions: rows.slice(0, 50) });
+                }
+                catch (error) {
+                    send(200, { ok: false, error: `transcript list failed: ${error instanceof Error ? error.message : String(error)}` });
+                }
+                return;
+            }
+            try {
+                const tail = readSessionLogTail(id, limit);
+                if (!tail.ok)
+                    send(200, { ok: false, error: tail.error });
+                else
+                    send(200, { ok: true, id: tail.id, count: tail.messages.length, messages: tail.messages });
+            }
+            catch (error) {
+                send(200, { ok: false, error: `transcript failed: ${error instanceof Error ? error.message : String(error)}` });
+            }
+        },
+    }), 'a2a: peer log face endpoint');
+    // W7 slice 2: the S1 outcome-retrieval surface — a READ-ONLY lookup of
+    // one claimed task's settled outcome. The body carries ONLY the task id
+    // and the submit payload's fingerprint (peerPayloadFingerprint, the
+    // gate's own shared implementation): the fingerprint match is the
+    // authorization, and the fan-out probe never leaks the original message
+    // to peers that never saw it. Constant-200 semantics — a query NEVER
+    // produces a wire error code (the frozen -32002/-32003 vocabulary stays
+    // submit-only), never claims, never steers, never enters a session: the
+    // gate's "verdict before steer" has its mirror in "a query executes
+    // nothing". Malformed fields degrade to unknown-task rather than
+    // guessing; an unparseable body answers 400 like /a2a/direct.
+    ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/a2a/query',
+        handler: (req, res) => {
+            const chunks = [];
+            let size = 0;
+            let overflowed = false;
+            req.on('data', (chunk) => {
+                if (overflowed)
+                    return;
+                const next = size + chunk.length;
+                if (next > 65_536) {
+                    overflowed = true;
+                    chunks.length = 0;
+                    return;
+                }
+                size = next;
+                chunks.push(chunk);
+            });
+            req.on('error', () => {
+                if (!res.headersSent) {
+                    res.writeHead(400);
+                    res.end();
+                }
+            });
+            req.on('end', () => {
+                if (overflowed) {
+                    if (!res.writableEnded && !res.headersSent) {
+                        const payload = JSON.stringify({ error: 'payload too large', code: WIRE_ERROR_PAYLOAD_TOO_LARGE });
+                        res.writeHead(413, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                        res.end(payload);
+                    }
+                    return;
+                }
+                let body;
+                try {
+                    body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                }
+                catch {
+                    const payload = JSON.stringify({ error: 'malformed body', code: -32000 });
+                    res.writeHead(400, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                    res.end(payload);
+                    return;
+                }
+                const taskId = typeof body.task_id === 'string' ? body.task_id : '';
+                const fingerprint = typeof body.fingerprint === 'string' ? body.fingerprint : '';
+                const verdict = taskId === '' || fingerprint === ''
+                    ? { found: false, reason: 'unknown-task' }
+                    : idempotencyStore.query(taskId, fingerprint);
+                const payload = JSON.stringify(verdict.found
+                    ? verdict.status === 'pending'
+                        ? { found: true, status: 'pending', task_id: taskId }
+                        : verdict.status === 'completed'
+                            ? {
+                                found: true,
+                                status: 'completed',
+                                reply: verdict.reply,
+                                settled_at: new Date(verdict.settledAt).toISOString(),
+                                task_id: taskId,
+                                ...(verdict.truncated === true ? { truncated: true } : {}),
+                            }
+                            : {
+                                found: true,
+                                status: 'failed',
+                                error: verdict.error,
+                                settled_at: new Date(verdict.settledAt).toISOString(),
+                                task_id: taskId,
+                                ...(verdict.truncated === true ? { truncated: true } : {}),
+                            }
+                    : { found: false, reason: verdict.reason, task_id: taskId });
+                res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                res.end(payload);
+            });
+        },
+    }), 'a2a: query endpoint');
+    ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/a2a/direct',
+        handler: async (req, res) => {
+            const chunks = [];
+            let size = 0;
+            // B5 enforcement: 512 KiB hard cap. An oversized body is rejected,
+            // never truncated and never connection-killed mid-read — buffering
+            // stops at the crossing chunk, the stream drains to `end`, and the
+            // peer receives one structured 413 with a wire error code (the old
+            // behavior tore the socket down with no diagnosis at all).
+            let overflowed = false;
+            const declared = Number.parseInt(String(req.headers['content-length'] ?? ''), 10);
+            if (Number.isFinite(declared) && !withinRouteBodyCap(declared))
+                overflowed = true;
+            req.on('data', (chunk) => {
+                if (overflowed)
+                    return;
+                const next = size + chunk.length;
+                if (!withinRouteBodyCap(next)) {
+                    overflowed = true;
+                    chunks.length = 0;
+                    return;
+                }
+                size = next;
+                chunks.push(chunk);
+            });
+            /* v8 ignore next 6 -- client aborts surface as 'close' via the shared
+               webServer's per-request guard; a raw req 'error' needs a malformed
+               HTTP stream the webServer rejects before this handler exists */
+            req.on('error', () => {
+                if (!res.headersSent) {
+                    res.writeHead(400);
+                    res.end();
+                }
+            });
+            req.on('end', async () => {
+                if (overflowed) {
+                    if (!res.writableEnded && !res.headersSent) {
+                        const payload = JSON.stringify({ error: 'payload too large', code: WIRE_ERROR_PAYLOAD_TOO_LARGE });
+                        res.writeHead(413, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                        res.end(payload);
+                    }
+                    return;
+                }
+                let body;
+                try {
+                    body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                }
+                catch {
+                    const payload = JSON.stringify({ error: 'malformed body', code: -32000 });
+                    res.writeHead(400, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                    res.end(payload);
+                    return;
+                }
+                // V2 (gh#7, S1): the delivery face honors the apiKey gate exactly
+                // like the control face — a configured key without this header
+                // used to let anyone reachable steer sessions while the control
+                // routes demanded the key, making it decorative for delivery.
+                // Empty-key deployments keep the documented open posture.
+                if (config.apiKey !== '') {
+                    const presented = String(req.headers['x-api-key'] ?? '');
+                    if (!secretEqual(presented, config.apiKey)) {
+                        const payload = JSON.stringify({ error: 'unauthorized: X-API-Key required on the delivery face (apiKey is configured)', code: -32000 });
+                        res.writeHead(401, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                        res.end(payload);
+                        return;
+                    }
+                }
+                const team = typeof body.team === 'string' ? body.team : '';
+                const message = typeof body.message === 'string' ? body.message : '';
+                const caller = typeof body.caller_session === 'string' ? body.caller_session : '';
+                // P2 receipt-callback: where THIS node's receipt should route on
+                // the caller's side — the caller knows its routable address best
+                // (a joined session's node team, e.g. via the transport face's
+                // callbackTarget mapping). Bounded; absent → the caller label
+                // plays its usual role.
+                const callback = typeof body.callback === 'string' && body.callback !== '' && body.callback.length <= 128 ? body.callback : '';
+                const noWait = body.wait === false;
+                const contextId = typeof body.context_id === 'string' && body.context_id !== '' ? body.context_id : `ctx-${Math.random().toString(16).slice(2, 10)}`;
+                // The caller-born task id (idempotency key): echo it when present
+                // so the receipt header correlates with the caller's own result;
+                // pre-0.5.3 callers carry none and this node mints one.
+                const taskId = typeof body.task_id === 'string' && body.task_id !== '' ? body.task_id : `direct-${Math.random().toString(16).slice(2, 10)}`;
+                if (team === '' || message === '') {
+                    const payload = JSON.stringify({ error: 'team and message are required', code: -32000 });
+                    res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                    res.end(payload);
+                    return;
+                }
+                // Phase-3 admission (owner ruling 2026-09-01, decision-seat
+                // filed): an inbound direct delivery must show a SHARED team.
+                // Local-zone callers are judged synchronously and exactly — the
+                // declaration lives in this host's own roster store, so the
+                // Anonymous-delivery refusal (S3 phase-3b, test-seat finding
+                // direct-001649ab): a delivery with NO caller_session field
+                // skips the admission gate entirely (nothing to judge) — that
+                // anonymous hole let any local process or reachable peer inject
+                // into a live session. The protocol contract is caller_session;
+                // its absence is now refused instead of silently waved through.
+                // (0.6.15: the rule now lives in a2aCallerRefusal so the
+                // read-only /a2a/log face admits callers by exactly the same
+                // standard as message delivery.)
+                const callerRefusal = a2aCallerRefusal(caller, team);
+                if (callerRefusal !== undefined) {
+                    recordActivity('in', team, caller === '' ? 'anonymous' : caller, false);
+                    const payload = JSON.stringify({ error: callerRefusal, code: -32000, team, task_status: 'TASK_STATE_FAILED' });
+                    res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                    res.end(payload);
+                    return;
+                }
+                // gh#9+gh#10 OriginClaim on the delivery face (M1): an envelope
+                // that is present but unverifiable rejects untrusted-origin; an
+                // ABSENT envelope during the window walks on with a counted
+                // legacyInbound warn (the operator watches the tail drain), and
+                // after the window closes it rejects like a failed signature —
+                // N3 proves a NAME's linkability, never key possession.
+                const claim = await verifyOriginClaim(req);
+                if (!claim.ok) {
+                    if (claim.reason !== 'absent' || config.originClaimWindow === false) {
+                        recordActivity('in', team, caller, false);
+                        const payload = JSON.stringify({ error: `untrusted-origin: OriginClaim verification failed (${claim.reason}) — present a signed envelope (X-A2A-Caller/-Url/-Ts/-Sig with your card key) or upgrade your node`, code: -32000, team, task_status: 'TASK_STATE_FAILED' });
+                        res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                        res.end(payload);
+                        return;
+                    }
+                    d.bumpLegacyInbound();
+                }
+                if (refuseIfBudgetExhausted(req, res, team, caller, taskId, taskLedger))
+                    return;
+                // Server-side idempotency (P3/B3): one key, one execution inside
+                // the window. Same key + same payload ⇒ replay; different payload
+                // ⇒ hard conflict (both 409). A replay must never re-enter the
+                // target session, no matter how it settles.
+                const idemFingerprint = peerPayloadFingerprint({ caller, message, noWait, team });
+                const idemVerdict = idempotencyStore.claim(taskId, idemFingerprint);
+                if (idemVerdict !== 'fresh') {
+                    const replay = idemVerdict === 'replay';
+                    // Conflicts warn (caller key reuse bugs); harmless replays stay silent.
+                    if (!replay)
+                        logger.warn(`a2a: idempotency CONFLICT on task ${taskId.slice(0, 80)} — same key reused with a different payload (caller bug; never auto-retry)`);
+                    const payload = JSON.stringify({
+                        error: replay ? 'duplicate task id within the idempotency window' : 'task id reused with a different payload',
+                        code: replay ? WIRE_ERROR_REPLAY_REJECTED : WIRE_ERROR_IDEMPOTENCY_CONFLICT,
+                        task_id: taskId,
+                        replay,
+                    });
+                    res.writeHead(409, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                    res.end(payload);
+                    return;
+                }
+                if (refuseIfFlooded(caller, message, team, taskId, res))
+                    return;
+                // The caller-side receipt correlation: a message shaped as a
+                // receipt resolves the task it echoes, whichever wait semantics
+                // carried it here. Correlation is bookkeeping only — the message
+                // steers on exactly as before.
+                settleAndAnnounce(message);
+                // gh#45 CLI mailbox (wire face): a delivery targeting a DEPOSITED
+                // CLI handle never resolves a session and never wakes — it lands
+                // in the deposit's mailbox and answers delivered. Placement here
+                // keeps the idempotency claim (above) exactly as for sessions.
+                const cliRow = cliDeposits.get(team);
+                if (cliRow !== undefined) {
+                    cliDeposits.mail(team, caller, message);
+                    recordActivity('in', team, caller, true);
+                    logger.info(`a2a: cli mailbox delivery for ${team} (from ${caller})`);
+                    const payload = JSON.stringify({ routed: true, delivered: true, receipt: 'mailbox', team, task_id: taskId, task_status: 'TASK_STATE_COMPLETED', note: `delivered to the mailbox of ${team} — the CLI polls while online` });
+                    res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                    res.end(payload);
+                    return;
+                }
+                // Inbound routing is foreground demand: boot prewarm yields for a
+                // quiet window around it.
+                d.touchWakeDemand();
+                // wait:false delivers without the final-reply hold: steer resolves
+                // synchronously inside routeIntoAgentFor, so by the time the agent
+                // lookup settles the message is already in — answer delivered and
+                // let the receipt contract carry the reply.
+                if (noWait) {
+                    // Issue #41 companion fix: the no-wait inbound branch resolved
+                    // only bare session teams — a canvas team delivery (wait:false)
+                    // fell through to the cold tier and answered a bogus
+                    // no-match although a live member existed. Same resolution as
+                    // the waiting face (routeIntoAgent), and likewise NO initiator
+                    // skip: the wire face delivers faithfully to the first live
+                    // member, whoever the caller is.
+                    const agent = resolveAgentForTeam(team) ?? canvasLiveAgent(parseCanvasTeamName(team));
+                    const wake = agent !== undefined ? undefined : wakeColdTeam(team);
+                    const deliver = (target) => {
+                        const from = caller === '' ? 'an unknown node' : caller;
+                        // The receipt target: the caller's callback address when it
+                        // supplied one (a session node team — wake-on-route covers a
+                        // cold one), else the caller label as before.
+                        const receiptTarget = callback !== '' ? callback : from;
+                        try {
+                            // The receipt header carries the task id: the target echoes
+                            // it verbatim in "[A2A receipt] task <id> ...", closing the
+                            // correlation loop with the caller's own route result.
+                            // F1' (consumed-probe prior-running): capture the pre-steer
+                            // status first — a target that was already running (its own
+                            // turn / a brand-new session's activation window) reads
+                            // `running` after the steer whether or not our wake was
+                            // latched, so the post-steer read alone would answer a false
+                            // consumed:true and strand the message.
+                            const runningBeforeSteer = probeConsumption(target, taskId);
+                            steerRelay(target, `[A2A direct] (task ${taskId}) ${fromClause(from)} (routed to ${team}) sent:\n\n${message}\n\n(When done, route your outcome back with one call — a2a_route { team: "${receiptTarget}", message: "[A2A receipt] task ${taskId} <one-line outcome>" }.)`, from === 'an unknown node' ? undefined : from);
+                            recordActivity('in', team, caller, true);
+                            armReceiptAutosend(target, taskId, receiptTarget, message);
+                            // v0.5.23 (async-stall): "delivered" only proves the steer call
+                            // returned — not that a turn started. An idle-phase steer wakes
+                            // the driver, but a maintenance/abort window latches the wake for
+                            // replay that may never fire (defect t-mt6nd0sq-hxuhj6: seven
+                            // delivered:true routes with zero log growth). Probe the driver
+                            // shortly after: running means the message is being consumed;
+                            // still-idle means the wake was latched or dropped — surface that
+                            // honestly and arm a delayed nudge retry below.
+                            // F1': a prior-running target never trusts the single
+                            // post-steer read — answer consumed:false conservatively and
+                            // arm the nudge (a false negative costs one harmless nudge; a
+                            // false positive strands the delivered message).
+                            // F2' (receipt-settlement): the delivery is born into the
+                            // ledger — an inbound row owes a receipt only this node can
+                            // produce, and before this row existed the nudge's isPending
+                            // gate no-op'd for exactly the deliveries that stall (08-30:
+                            // zero ledger records for latched activations). Arming is
+                            // unconditional now; settlement evidence disarms in the
+                            // callback.
+                            const consumedProbe = runningBeforeSteer ? false : probeConsumption(target, taskId);
+                            // F5 (settlement integrity): the debt gate — a process-label
+                            // caller cannot receive receipts, so this delivery is born
+                            // fire-and-forget (receiptExpected:false, answered as
+                            // receipt:"none") instead of manufacturing a debt nobody can
+                            // settle. The row itself stays: stall visibility and the
+                            // nudge still apply to the TARGET side.
+                            const receiptExpectation = receiptExpectationOf(receiptTarget);
+                            taskLedger.trackInbound(taskId, team, receiptTarget, contextId === '' ? undefined : contextId, receiptExpectation !== 'process-label', briefOf(message));
+                            armAsyncNudge(target, team, taskId, config.asyncNudgeDelayMs);
+                            const payload = JSON.stringify({
+                                routed: true,
+                                delivered: true,
+                                team,
+                                session,
+                                task_id: taskId,
+                                context_id: contextId,
+                                task_status: 'TASK_STATE_DELIVERED',
+                                artifacts: [],
+                                consumed: consumedProbe,
+                                receipt: receiptExpectation === 'process-label' ? 'none' : 'routed',
+                            });
+                            res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                            res.end(payload);
+                        }
+                        catch (error) {
+                            recordActivity('in', team, caller, false);
+                            const payload = JSON.stringify({ error: `The DSH session rejected the message: ${String(error)}`, code: -32000, team, task_id: taskId, task_status: 'TASK_STATE_FAILED' });
+                            res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                            res.end(payload);
+                        }
+                    };
+                    if (agent !== undefined) {
+                        deliver(agent);
+                        return;
+                    }
+                    if (wake?.kind === 'flight') {
+                        void wake.flight.then(deliver, (error) => {
+                            recordActivity('in', team, caller, false);
+                            const payload = JSON.stringify({ error: `waking the session for team "${team}" failed: ${String(error)}`, code: -32000, team, task_status: 'TASK_STATE_FAILED' });
+                            res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                            res.end(payload);
+                        });
+                        return;
+                    }
+                    // Remaining candidates need one async classification (the
+                    // native-teams bridge), so the tail answers inside an IIFE.
+                    void (async () => {
+                        // Native-teams inbound bridge (opt-in): prepare BEFORE answering
+                        // delivered — claim, seam, and parent initiator are everything
+                        // that can fail fast, and a phantom dispatch must never answer
+                        // success. Past prepare, the round fires detached (noWait means
+                        // delivery, not settlement); its late outcome corrects the
+                        // activity ring and the log.
+                        const standardMiss = () => {
+                            if (team === config.team) {
+                                const live = liveAgent();
+                                if (live !== undefined) {
+                                    // Self-route refusal (mirrors the sync face): a caller
+                                    // naming the very agent the fallback resolves to must
+                                    // get an honest failure, never its own dispatch echoed
+                                    // home plus an auto-receipt for work nobody did.
+                                    if (callerIsAgent(live, caller)) {
+                                        recordActivity('in', team, caller, false);
+                                        const payload = JSON.stringify({ error: selfRouteText(team), code: -32000, team, task_status: 'TASK_STATE_FAILED' });
+                                        res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                                        res.end(payload);
+                                        return;
+                                    }
+                                    deliver(live);
+                                    return;
+                                }
+                            }
+                            const payload = JSON.stringify({ error: wake?.kind === 'no-face' ? noWakeFaceText(team) : wake?.kind === 'archived' ? archivedColdMatchText(team) : noColdMatchText(team), code: -32000, team, task_status: 'TASK_STATE_FAILED' });
+                            res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                            res.end(payload);
+                        };
+                        const prepared = await nativeTeamsPrepare(team);
+                        if (!prepared.ok) {
+                            if (prepared.reason === 'error') {
+                                recordActivity('in', team, caller, false);
+                                const payload = JSON.stringify({ error: prepared.error, code: -32000, team, task_status: 'TASK_STATE_FAILED' });
+                                res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                                res.end(payload);
+                                return;
+                            }
+                            standardMiss();
+                            return;
+                        }
+                        recordActivity('in', team, caller, true);
+                        void nativeTeamsRound(prepared, team, caller, message, taskId)
+                            .then(outcome => {
+                            if (!outcome.ok) {
+                                recordActivity('in', team, caller, false);
+                                logger.warn(`a2a: detached native-teams round for "${team}" failed: ${outcome.error}`);
+                            }
+                            // W7 slice-2 hook 2: only a genuinely settled detached round
+                            // records an outcome. The deadline's settled:false
+                            // projection is a placeholder, not a product — the same
+                            // ruling as hook 1's DELIVERED skip; placeholder prose never
+                            // enters the ledger a replay could adopt from.
+                            if (taskId !== '') {
+                                if (!outcome.ok)
+                                    idempotencyStore.recordOutcome(taskId, { status: 'failed', error: outcome.error });
+                                else if (outcome.settled)
+                                    idempotencyStore.recordOutcome(taskId, { status: 'completed', reply: outcome.reply });
+                            }
+                        });
+                        const payload = JSON.stringify({ routed: true, delivered: true, team, session, task_id: taskId, context_id: contextId, task_status: 'TASK_STATE_DELIVERED', artifacts: [], consumed: false, bridge: 'native-teams' });
+                        res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                        res.end(payload);
+                    })();
+                    return;
+                }
+                void routeIntoAgent(team, message, caller, taskId).then((outcome) => {
+                    recordActivity('in', team, caller, outcome.ok);
+                    // W7 slice-2 hook 1: record the settled outcome on the claim row.
+                    // Ruling: a non-COMPLETED status (TASK_STATE_DELIVERED — the
+                    // bridge-round deadline placeholder, ABORTED_WAIT likewise) is
+                    // NOT a settled outcome, and neither is a host-authored
+                    // placeholder on the reply channel (flush timeout, dead session)
+                    // — the row stays pending, because an adopted replay must never
+                    // settle a node on placeholder text (the exact hazard W7 gap B
+                    // closed, barred from resurrecting through the outcome ledger).
+                    if (taskId !== '') {
+                        if (!outcome.ok) {
+                            idempotencyStore.recordOutcome(taskId, { status: 'failed', error: outcome.error });
+                        }
+                        else if (outcome.placeholder === true) {
+                            // placeholder prose never enters the ledger
+                        }
+                        else if (outcome.status === undefined || outcome.status === 'TASK_STATE_COMPLETED') {
+                            idempotencyStore.recordOutcome(taskId, { status: 'completed', reply: outcome.reply });
+                        }
+                    }
+                    const payload = outcome.ok
+                        ? JSON.stringify({
+                            routed: true,
+                            team,
+                            session,
+                            result: { text: outcome.reply },
+                            task_id: taskId,
+                            context_id: contextId,
+                            task_status: outcome.status ?? 'TASK_STATE_COMPLETED',
+                            artifacts: [],
+                            // The bridge marker rides the wire so the caller's
+                            // trackOwedTask skips a receipt-less native round — without
+                            // it, a cross-node unsettled round books an unpayable owed
+                            // row and re-creates the TASK_CAP backlog.
+                            ...(outcome.bridge !== undefined ? { bridge: outcome.bridge } : {}),
+                        })
+                        : JSON.stringify({ error: outcome.error, code: -32000, team, task_id: taskId, task_status: 'TASK_STATE_FAILED' });
+                    res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                    res.end(payload);
+                });
+            });
+        },
+    }), 'a2a: direct route endpoint');
+}