@nelsonlongxiang/dsh-open-a2a-net 0.6.36 → 0.6.38

package/lib/index.js

@@ -31,12 +31,15 @@ import { GroupStore } from "./group-store.js";
 import { CanvasStore, canvasNameReserved, isRemoteMemberRef } from "./canvas-store.js";
 import { decodeSessionLog, extractTranscript, TRANSCRIPT_MAX_FILE_BYTES } from "./session-transcript.js";
 import { LayoutStore } from "./layout-store.js";
+import { peerLinkDisplay } from "./peer-link-display.js";
+import { canvasOwners, canvasFailure } from "./canvas-discovery.js";
 import { JoinedSessions } from "./joined-store.js";
 import { ExposureStore } from "./exposure-store.js";
+import { loadSeatNames } from "./owner-settings.js";
 import { CLI_HANDLE_RE, CliDepositStore } from "./cli-deposit.js";
 import { cliHomeChoices, decideCliHome } from "./cli-home.js";
 import { outboundScope } from "./outbound-scope.js";
-import { createDirectForward } from "./direct-forward.js";
+import { createDirectForward, ForwardBirths } from "./direct-forward.js";
 import { TeamMembershipStore } from "./team-store.js";
 import { PeerStore } from "./peer-store.js";
 import { SelfReferralFilter } from "./self-suppress.js";
@@ -87,7 +90,7 @@ export const Config = s.object({
     settlementAuth: s.union(['off', 'observe', 'enforce']).default('observe'),
     announce: s.boolean().default(false),
     isolated: s.boolean().default(false),
-    forwardDirect: s.boolean().default(false),
+    forwardDirect: s.boolean().default(true),
     agentName: s.string().default('DeepSeek Harness A2A node'),
     peers: s.array(s.string()).default([]),
     delegates: s.array(s.object({ name: s.string(), url: s.string(), publicKey: s.string().default('') })).default([]),
@@ -111,6 +114,7 @@ export const Config = s.object({
      * refused join carries guidance instead of failing silently.
      */
     teamJoinAllowlist: s.array(s.string()).default([]),
+    seatNames: s.dict(s.any()).default({}),
     /**
      * S3 (phase-2 default, owner ruling 2026-09-01): route dispatch checks
      * caller↔target shared team membership before addressing — a session
@@ -570,7 +574,9 @@ export function apply(ctx, config) {
      * request) and the relay/notify faces.
      */
     function originClaimHeaders(target) {
-        return signOriginClaim(target, { caller: config.team, callerUrl: ownCardUrl, privateKey: nodePrivateKey, unbound: config.originClaimUnboundWindow !== false, now: Date.now() });
+        // No local web/card anchor yet: keep the preexisting absent-envelope migration posture, not a malformed Sig3.
+        const signedTarget = ownCardUrl === '' ? { url: target.url, method: target.method } : target;
+        return signOriginClaim(signedTarget, { caller: config.team, callerUrl: ownCardUrl, privateKey: nodePrivateKey, unbound: config.originClaimUnboundWindow !== false, now: Date.now() });
     }
     const client = new A2aClient({
         apiKey: config.apiKey,
@@ -598,6 +604,8 @@ export function apply(ctx, config) {
     // are read at call time, so the panel's write applies WITHOUT a restart;
     // announce is boot-time publishing (restart pending flag for the UI).
     let ownerAllowlist = [...(config.teamJoinAllowlist ?? [])];
+    let ownerSeatNames = loadSeatNames(config.seatNames ?? {}, reason => logger.warn(reason));
+    ctx.tools.guard(exec => exec.name.startsWith('a2a_') && exec.arguments !== null && typeof exec.arguments === 'object' && (Object.hasOwn(exec.arguments, 'seatName') || Object.hasOwn(exec.arguments, 'seatNames')) ? 'seatName is human-owned; use the workbench owner settings, not model tools' : undefined);
     // Truthiness matches the ORIGINAL read site (`if (config.teamScopeInfo)`):
     // literal compositions without the schema default carry undefined, which
     // reads as the OPEN plane — `!== false` would silently scope them.
@@ -675,7 +683,13 @@ export function apply(ctx, config) {
     // queryable here, and the correlating `[A2A receipt] task <id>` message
     // resolves it — the caller-side half of the receipt contract, persisted so
     // a restart does not orphan the reconciliation.
-    const taskLedger = new TaskLedger(join(home, 'a2a', 'tasks.json'), { staleTtlMs: config.taskStaleTtlMs });
+    const taskLedger = new TaskLedger(join(home, 'a2a', 'tasks.json'), { staleTtlMs: config.taskStaleTtlMs, warn: message => logger.warn(message) });
+    const enforceBlockers = taskLedger.settlementEnforceBlockers();
+    const enforceRefused = config.settlementAuth === 'enforce' && enforceBlockers.length > 0 ? { reason: 'legacy forwarded canvas debts lack receiver facts', blockers: enforceBlockers } : undefined;
+    if (enforceRefused !== undefined) {
+        logger.error('settlementAuth enforce refused; running observe (#125/#275): %s', JSON.stringify(enforceRefused));
+        config = { ...config, settlementAuth: 'observe' };
+    }
     // Unjoined-node reporting ingress (design: docs/design/unjoined-report-ingress.md):
     // a one-way signal channel for sessions with no network membership — a
     // fallen-off or never-joined session reports "I exist / I have a task"
@@ -720,6 +734,12 @@ export function apply(ctx, config) {
      * the consumer's own discipline — keep seam listeners synchronous.
      * @param message - the inbound or relayed message text.
      */
+    const forwardingBirths = new ForwardBirths();
+    async function waitForForwardBirth(message) {
+        const receipt = parseReceipt(message);
+        if (receipt !== null)
+            await forwardingBirths.wait(receipt.taskId);
+    }
     function settleAndAnnounce(message, settler) {
         const parsedForJudge = parseReceipt(message);
         const judge = settlementJudgeFor(settler, parsedForJudge);
@@ -1253,14 +1273,15 @@ export function apply(ctx, config) {
     const LEGACY_PREWARM_PROBE_TITLE = '[prewarm] 请回复 ok。';
     function nodeMetadataOf(agent) {
         const title = sessionTitleOf(agent);
-        const cwd = agent.session.header?.cwd;
+        const cwd = agent.session?.header?.cwd;
         // Display-layer fallback (pure presentation, zero data mutation): a title
         // that IS the legacy probe reads as machine junk in every directory and
         // card — surface the stable seat label instead. The session-title
         // service's stored value is untouched.
         const displayTitle = title !== undefined && title !== '' && title !== LEGACY_PREWARM_PROBE_TITLE ? title : undefined;
         return {
-            name: displayTitle !== undefined ? displayTitle : sessionLabelOf(agent),
+            name: ownerSeatNames[String(agent.id)] ?? (displayTitle !== undefined ? displayTitle : sessionLabelOf(agent)),
+            ...(ownerSeatNames[String(agent.id)] !== undefined ? { seatName: ownerSeatNames[String(agent.id)] } : {}),
             description: recentActivityOf(agent),
             ...(cwd !== undefined && cwd !== '' ? { workspace: cwd } : {}),
         };
@@ -1652,13 +1673,16 @@ export function apply(ctx, config) {
             // gh#77 B1: the admin faces live in src/faces/admin.ts.
             registerAdminFaces(webServer, {
                 ctx, config, logger, home, session, lanIp, PLUGIN_VERSION, controlRoute, controlTrustedWithoutKey, readJsonBody, peerFetch, peerStore, peerLinkState, originClaimHeaders, refreshRemoteRows, joinedSessions, exposureStore, teamMemberships, cliDeposits, groupStore, canvasStore, cliHomeForAdd, cliHomeOptions, layoutStore, taskLedger, idempotencyStore, inFlightRoutes, recentActivity, teamAuditRing, reportRing, sessionNodes, liveRoots, mountSessionNode, coldJoinedIds, prewarmStatus, reconcileStatus, id8, sessionLabelOf, sessionTeamOf, ownCanvasHandleOf, localSessionOfHandle, canvasTeamsOfSession, nodeMetadataOf, canvasTeamOf, archivedSessionFilter, pruneArchivedJoins, pruneCanvasMemberships, verifyOriginClaim, callerLinkedToThisHost, cachedCardFetch, authorizationView,
-                indexUrl: import.meta.url,
+                indexUrl: import.meta.url, enforceRefused,
                 get cardCache() { return cardCache; },
                 get remoteRowsCache() { return remoteRowsCache; },
                 get legacyInboundCount() { return legacyInboundCount; },
                 get unboundInboundCount() { return unboundInboundCount; },
                 get boundMissInboundCount() { return boundMissInboundCount; },
+                get boundMissRecent() { return boundMissRecent; },
                 get ownCardUrl() { return ownCardUrl; },
+                get ownerSeatNames() { return ownerSeatNames; },
+                set ownerSeatNames(v) { ownerSeatNames = v; },
                 get ownerAllowlist() { return ownerAllowlist; },
                 set ownerAllowlist(v) { ownerAllowlist = v; },
                 get ownerTeamScopeInfo() { return ownerTeamScopeInfo; },
@@ -1776,7 +1800,7 @@ export function apply(ctx, config) {
                         ...[...sessionNodes.values()].filter(isJoinedNode).map(agent => exposureRow(sessionTeamOf(agent), nodeMetadataOf(agent))),
                         ...joinedSessions.list()
                             .filter(id => !liveRoots.has(id) && isArchived?.(id) !== true)
-                            .map(id => exposureRow(`${config.team}/${id8(id)}`, { name: `${session}-${id8(id)}`, description: 'cold — not loaded; routing here wakes the session' })),
+                            .map(id => exposureRow(`${config.team}/${id8(id)}`, { name: ownerSeatNames[id] ?? `${session}-${id8(id)}`, ...(ownerSeatNames[id] !== undefined ? { seatName: ownerSeatNames[id] } : {}), description: 'cold — not loaded; routing here wakes the session' })),
                         // gh#45/47: deposited CLI identities publish as directory rows —
                         // the fleet sees them as member cards (draggable = the operator
                         // link). Their "zone" is the agent-name. gh#47: an EXPIRED
@@ -2111,15 +2135,15 @@ export function apply(ctx, config) {
      * marker instead of a (false) completion.
      * @param taskId - the correlation key the steered receipt header carries.
      */
-    async function routeIntoAgent(team, message, caller, taskId, proofClause, buildHeader, localFrom) {
+    async function routeIntoAgent(team, message, caller, taskId, proofClause, buildHeader, localFrom, onSteered) {
         const agent = resolveAgentForTeam(team) ?? canvasLiveAgent(parseCanvasTeamName(team));
         if (agent !== undefined) {
-            return routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom);
+            return routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom, onSteered);
         }
         // Wake-on-route: a cold joined team materializes on demand, then steers.
         const wake = wakeColdTeam(team);
         if (wake.kind === 'flight') {
-            return wake.flight.then(agent => routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom), (error) => ({ ok: false, error: `waking the session for team "${team}" failed: ${String(error)}` }));
+            return wake.flight.then(agent => routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom, onSteered), (error) => ({ ok: false, error: `waking the session for team "${team}" failed: ${String(error)}` }));
         }
         // Native-teams inbound bridge (opt-in): a registry team claims the
         // handle and dispatches through its authoritative seam. Checked before
@@ -2148,7 +2172,7 @@ export function apply(ctx, config) {
             if (live !== undefined) {
                 if (callerIsAgent(live, caller))
                     return { ok: false, error: selfRouteText(team) };
-                return routeIntoAgentFor(live, team, message, caller, taskId, proofClause, buildHeader);
+                return routeIntoAgentFor(live, team, message, caller, taskId, proofClause, buildHeader, undefined, onSteered);
             }
             return { ok: false, error: 'No live DSH agent is available to accept this message.' };
         }
@@ -2163,7 +2187,7 @@ export function apply(ctx, config) {
      * @param caller - caller label for the steered prefix.
      * @returns the agent's final reply, or the explicit failure.
      */
-    function routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom) {
+    function routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom, onSteered) {
         return new Promise((resolve) => {
             const waiter = registerFinalWaiter(agent, (text, placeholder) => {
                 resolve({ ok: true, reply: text, ...(placeholder === true ? { placeholder: true } : {}) });
@@ -2180,7 +2204,11 @@ export function apply(ctx, config) {
                 : `[A2A direct] ${taskId === undefined ? '' : `(task ${taskId}) `}未验证（in-process） ${sanitizeFromClause(from)} (routed to ${team}) sent:`;
             const text = `${headerLine}\n\n${message}`;
             try {
+                const floor = sessionEventsOf(agent).length;
                 steerRelay(agent, text, caller === '' ? undefined : caller, localFrom);
+                onSteered?.(agent, floor);
+                if (onSteered !== undefined && sessionEventsOf(agent).slice(floor).some(event => event?.type === 'assistant/message'))
+                    queueMicrotask(() => flushFinals(String(agent.id))); // synchronous final may already have emitted idle
             }
             catch (error) {
                 // The waiter was registered above, so the key always holds it; the
@@ -2213,6 +2241,15 @@ export function apply(ctx, config) {
      *  closing originClaimUnboundWindow; boundMissInbound: those of them whose
      *  bound form missed (a peer dials us by a name not in our audiences). */
     let unboundInboundCount = 0, boundMissInboundCount = 0;
+    /** Which verified callers missed, and the origin they dialled: what to add to originClaimAudiences (#64). */
+    const boundMissRecent = [];
+    const noteBoundMiss = (miss) => {
+        boundMissInboundCount += 1;
+        const at = boundMissRecent.findIndex(row => row.caller === miss.caller && row.audience === miss.audience);
+        const row = at >= 0 ? boundMissRecent.splice(at, 1)[0] : { ...miss, count: 0, lastAt: 0 };
+        boundMissRecent.unshift({ ...row, count: row.count + 1, lastAt: Date.now() });
+        boundMissRecent.length = Math.min(boundMissRecent.length, 16);
+    };
     function verifyOriginClaim(req, options) {
         return verifyOriginClaimOf(req, {
             cardCache,
@@ -2220,10 +2257,11 @@ export function apply(ctx, config) {
             audiences: [ownCardUrl, ...config.originClaimAudiences ?? []],
             unboundOpen: config.originClaimUnboundWindow !== false,
             onUnbound: () => { unboundInboundCount += 1; },
-            onBoundMiss: () => { boundMissInboundCount += 1; },
+            onBoundMiss: noteBoundMiss,
             loopbackArrival: (config.originClaimUrl ?? '') === '',
             now: Date.now(),
             ...(options?.cli === true ? { cliDeposit: cliDepositCard } : {}),
+            ...(options?.rawBody !== undefined ? { rawBody: options.rawBody } : {}),
         });
     }
     /**
@@ -2556,6 +2594,7 @@ export function apply(ctx, config) {
             verifyOriginClaim,
             remoteCliProof,
             forwardDirect: request => forwardDirect(request),
+            diagnoseCanvas: (team, reason, caller) => diagnoseCanvas(team, reason, caller),
             callerLinkedToThisHost, get ownCardUrl() { return ownCardUrl; },
             recordActivity,
             bumpLegacyInbound: () => { legacyInboundCount += 1; },
@@ -2569,7 +2608,7 @@ export function apply(ctx, config) {
             taskLedger,
             refuseIfFlooded,
             refuseIfQueueFull,
-            settleAndAnnounce,
+            settleAndAnnounce, waitForForwardBirth,
             touchWakeDemand: () => { lastWakeDemandAt = Date.now(); },
             session,
             resolveAgentForTeam,
@@ -2817,10 +2856,10 @@ export function apply(ctx, config) {
     }
     /**
      * gh#20 W-A: THIS host's view of one tracked peer's link state (the
-     * mirror of callerLinkedToThisHost, judged from our side about THEM):
-     *   · linked — bilateral seeding (our config.peers carries a URL of the
-     *     peer's origin AND the peer's card carries ours), or a canvas remote
-     *     ref naming the peer's zone or one of its session teams;
+     * display projection, not an admission decision:
+     *   · linked — bilateral URL seeding, or a canvas reference to an exact
+     *     nonlocal session handle uniquely advertised by that peer card key;
+     *     a shared zone or a minimal card alone never proves host identity;
      *   · stranger — no operator-established basis (a verified key is not a
      *     relationship);
      *   · verified — we hold a signature-valid cached card (the badge's
@@ -2835,6 +2874,15 @@ export function apply(ctx, config) {
      * Pure over warm caches and config; never fetches.
      */
     function peerLinkState(peerUrl) {
+        return peerLinkDisplay(peerUrl, {
+            card: cardCache.get(peerUrl)?.card, ownUrl: ownCardUrl, seeds: config.peers,
+            refs: canvasStore.list().flatMap(name => [...canvasStore.remoteMembersOf(name)]),
+            ownHandles: new Set([...joinedSessions.list(), ...liveRoots.keys()].map(id => `${config.team}/${id8(id)}`)),
+            cards: [...cardCache.values()].flatMap(entry => entry.card === undefined ? [] : [entry.card]),
+        });
+    }
+    // Compatibility for existing CLI home/admission semantics: badge projection must not change authorization.
+    function peerAdmissionLinkState(peerUrl) {
         const cached = cardCache.get(peerUrl)?.card;
         const verified = cached !== undefined;
         const zone = cached?.team ?? '';
@@ -2901,7 +2949,7 @@ export function apply(ctx, config) {
             const card = await fetchPeerCard(url).catch(() => undefined);
             if (card !== undefined)
                 cardCache.set(url, { at: Date.now(), card });
-            return { url, card, linked: card === undefined || peerLinkState(url).link === 'linked' };
+            return { url, card, linked: card === undefined || peerAdmissionLinkState(url).link === 'linked' };
         });
     }
     async function cliHomeForAdd(handle, requested) {
@@ -2935,7 +2983,7 @@ export function apply(ctx, config) {
             if (card === undefined || card.publicKey !== claim.card.publicKey)
                 continue;
             cardCache.set(url, { at: Date.now(), card });
-            if (peerLinkState(url).link !== 'linked')
+            if (peerAdmissionLinkState(url).link !== 'linked')
                 continue;
             const row = card.sessionTeams?.find(item => item.team === handle);
             if (row !== undefined)
@@ -3037,7 +3085,7 @@ export function apply(ctx, config) {
     };
     const SWEEP_CONCURRENCY = 6;
     const infoTools = createInfoTools({
-        ctx, config, logger, session, lanIp, ownCardUrl, peerStore, taskLedger,
+        ctx, config, logger, session, lanIp, get ownCardUrl() { return ownCardUrl; }, peerStore, taskLedger,
         inFlightRoutes, recentActivity, joinedSessions, sessionNodes, canvasStore,
         teamMemberships, exposureStore, idempotencyStore, cardCache,
         id8, sessionTeamOf,
@@ -3106,6 +3154,7 @@ export function apply(ctx, config) {
                     team: canvasTeamOf(name),
                     session,
                     name,
+                    kind: 'canvas', owner: ownCardUrl, memberCount: canvasStore.membersOf(name).length,
                     description: `canvas team — ${members.length} member${members.length === 1 ? '' : 's'}, ${live} live`,
                     local: true,
                     origin: localOrigin,
@@ -3284,7 +3333,40 @@ export function apply(ctx, config) {
      * caller label — the "能发即能收" invariant: whatever it addresses can
      * answer it with one route.
      */
+    const knownCanvasOwners = () => canvasOwners(canvasStore.list().map(name => ({ name, team: canvasTeamOf(name), members: canvasStore.membersOf(name) })), ownCardUrl, [...cardCache.entries()].flatMap(([url, entry]) => entry.card === undefined ? [] : [{ url, card: entry.card }]));
+    const diagnoseCanvas = async (team, reason, caller) => {
+        if (!new RegExp('^.+/canvas/[^/]+$').test(team))
+            return reason;
+        try {
+            await listDirectoryTeams(false, true);
+        }
+        catch (error) {
+            return reason + ' — canvas discovery unavailable: ' + String(error);
+        }
+        const resolve = localHandleResolver();
+        const localId = caller === undefined ? undefined : resolve(caller);
+        const owners = knownCanvasOwners().filter(row => !ownerTeamScopeInfo || (caller !== undefined && cliDeposits.get(caller) !== undefined) || (row.local ? localId !== undefined && row.members.some(ref => ref === localId || resolve(ref) === localId) : (row.scopeMembers ?? row.members).some(ref => { const id = resolve(ref); return id !== undefined && joinedSessions.has(id); })));
+        const missing = [];
+        if (caller !== undefined && cliDeposits.get(caller) !== undefined) {
+            if (!config.forwardDirect)
+                missing.push('home forwardDirect is off');
+            if (config.isolated)
+                missing.push('home is isolated');
+            const scope = config.teamScopeRouting ? await outboundScope(senderScopeRecords, caller, caller, team) : { ok: true };
+            if (!scope.ok)
+                missing.push('sender scope: ' + scope.error);
+            for (const owner of owners.filter(row => row.team === team && !row.local)) {
+                if (!owner.members.includes(caller))
+                    missing.push(owner.owner + ': caller is not an advertised canvas member');
+                for (const member of owner.members.filter(member => member !== caller))
+                    if (!canvasStore.list().some(name => canvasStore.remoteMembersOf(name).includes(member)))
+                        missing.push(owner.owner + ': missing direct operator link to receiver ' + member);
+            }
+        }
+        return canvasFailure(team, owners, reason) + (missing.length === 0 ? '' : ' — missing prerequisites: ' + missing.join('; '));
+    };
     const forwardDirect = createDirectForward({
+        births: forwardingBirths,
         enabled: () => config.forwardDirect === true, isolated: () => config.isolated, deposited: handle => cliDeposits.get(handle) !== undefined,
         memberLinked: handle => canvasStore.list().some(name => canvasStore.remoteMembersOf(name).includes(handle)),
         scope: (handle, team) => config.teamScopeRouting ? outboundScope(senderScopeRecords, handle, handle, team) : Promise.resolve({ ok: true }),
@@ -3343,7 +3425,7 @@ export function apply(ctx, config) {
                 scopedCanvasCaller = { id: scopeCaller, handle: callerHandle };
                 const scope = await outboundScope(senderScopeRecords, scopeCaller, callerHandle, String(args.team ?? '').trim());
                 if (!scope.ok)
-                    return localRoute(scope);
+                    return localRoute({ ...scope, error: await diagnoseCanvas(args.team, scope.error, callerHandle) });
             }
         }
         let callerSession = resolveCallerLabel({
@@ -3471,7 +3553,8 @@ export function apply(ctx, config) {
         }
         if (failures.length > 0)
             logger.warn(`route to team "${args.team}" exhausted its candidates: ${failures.join('; ')}`);
-        return routeVerdict(args.team, failures, candidatePool.length);
+        const verdict = routeVerdict(args.team, failures, candidatePool.length);
+        return { ...verdict, error: await diagnoseCanvas(args.team, verdict.error, callerSession) };
     }
     /**
      * The route dispatcher's local half: same-host candidates dial in-process,

package/lib/origin-claim.js

@@ -4,7 +4,7 @@
  * face (card, /a2a/direct, /a2a/log, /a2a/canvas-op, /a2a/canvas-changed)
  * runs.
  *
- * Two canonical forms ride the same four base headers
+ * Three canonical forms share the base caller headers
  * (X-A2A-Caller / -Url / -Ts):
  *   · bound (v2, §2.1): JSON.stringify([tag, caller, callerUrl, ts,
  *     audience, METHOD, path]) in X-A2A-Caller-Sig2, the audience origin in
@@ -14,18 +14,22 @@
  *   · unbound (v1, legacy): JSON.stringify([caller, callerUrl, ts]) in
  *     X-A2A-Caller-Sig. Emitted and accepted only while the unbound window
  *     is open (originClaimUnboundWindow); accepted ones are counted.
- * Once the window closes a present Sig2 is the only thing verified. While
+ * A present Sig3 requires the exact raw body and v3 signature, with no downgrade.
+ * Without Sig3, once the window closes a present Sig2 is the only thing verified. While
  * it is open, a Sig2 that misses (audience or signature) falls back to the
  * Sig the envelope also carries — no more than stripping Sig2 would give —
  * and the miss is counted, so a peer dialled by an unlisted name keeps
  * working through the rollout and shows on the gauge.
  */
-import { createPublicKey, sign as edSign, verify as edVerify } from 'node:crypto';
+import { createHash, createPublicKey, sign as edSign, verify as edVerify } from 'node:crypto';
 import { verifyCard } from "./card.js";
 /** ts skew tolerance (protocol constant, §7). */
 export const ORIGIN_CLAIM_SKEW_MS = 5 * 60_000;
 /** Domain tag of the bound form: a v1 signature can never verify as v2. */
 export const ORIGIN_CLAIM_BOUND_TAG = 'a2a-origin-claim/2';
+export const ORIGIN_CLAIM_BODY_TAG = 'a2a-origin-claim/3';
+/** Digest the exact UTF-8 string/bytes passed to transport, never reserialized JSON. */
+export const originBodySha256 = (body) => createHash('sha256').update(body).digest('base64url');
 /** Only the canonical origin root can claim that origin's identity. */
 export function isRootOriginUrl(value) {
     try {
@@ -62,6 +66,10 @@ export function unboundCanonical(caller, callerUrl, ts) {
 export function boundCanonical(caller, callerUrl, ts, audience, method, path) {
     return JSON.stringify([ORIGIN_CLAIM_BOUND_TAG, caller, callerUrl, ts, audience, method.toUpperCase(), path]);
 }
+/** The body-bound v3 form is domain-separated from v1/v2, with the digest appended. */
+export function bodyBoundCanonical(caller, callerUrl, ts, audience, method, path, bodySha256) {
+    return JSON.stringify([ORIGIN_CLAIM_BODY_TAG, caller, callerUrl, ts, audience, method.toUpperCase(), path, bodySha256]);
+}
 /** An origin in URL's normal form, or '' when the text is not an http(s) URL. */
 export function originOf(url) {
     try {
@@ -98,6 +106,11 @@ export function signOriginClaim(target, signer) {
     if (audience !== '') {
         headers['X-A2A-Caller-Aud'] = audience;
         headers['X-A2A-Caller-Sig2'] = sign(boundCanonical(caller, callerUrl, ts, audience, target.method, pathOf(target.url)));
+        if (target.body !== undefined) {
+            const digest = originBodySha256(target.body);
+            headers['X-A2A-Body-Sha256'] = digest;
+            headers['X-A2A-Caller-Sig3'] = sign(bodyBoundCanonical(caller, callerUrl, ts, audience, target.method, pathOf(target.url), digest));
+        }
     }
     if (signer.unbound)
         headers['X-A2A-Caller-Sig'] = sign(unboundCanonical(caller, callerUrl, ts));
@@ -153,15 +166,21 @@ export async function verifyOriginClaim(req, d) {
     const unboundSig = header('x-a2a-caller-sig');
     const boundSig = header('x-a2a-caller-sig2');
     const audience = header('x-a2a-caller-aud');
-    if (caller === '' || callerUrl === '' || !Number.isFinite(ts) || ts <= 0 || (unboundSig === '' && boundSig === ''))
-        return { ok: false, reason: 'absent' };
+    const hasBodySig = req.headers['x-a2a-caller-sig3'] !== undefined;
+    const bodySig = header('x-a2a-caller-sig3');
+    const digest = header('x-a2a-body-sha256');
+    // Presence, even malformed/empty, opts into v3. It must never become absent/legacy or fall back to Sig2/v1.
+    if (hasBodySig && (!bodySig || !/^[A-Za-z0-9_-]{43}$/.test(digest) || d.rawBody === undefined || originBodySha256(d.rawBody) !== digest))
+        return { ok: false, reason: 'body-mismatch' };
+    if (caller === '' || callerUrl === '' || !Number.isFinite(ts) || ts <= 0 || (unboundSig === '' && boundSig === '' && !hasBodySig))
+        return { ok: false, reason: hasBodySig ? 'bad-sig' : 'absent' };
     if (!originClaimCallerShape.test(caller))
         return { ok: false, reason: 'bad-caller-shape' };
     if (Math.abs(d.now - ts) > ORIGIN_CLAIM_SKEW_MS)
         return { ok: false, reason: 'bad-ts' };
-    const hasBound = boundSig !== '';
+    const hasBound = boundSig !== '' || hasBodySig;
     const audienceOk = hasBound && requestAudiences(req, d.audiences, d.loopbackArrival ?? true).has(originOf(audience));
-    const fallback = d.unboundOpen && unboundSig !== '';
+    const fallback = !hasBodySig && d.unboundOpen && unboundSig !== '';
     if (hasBound && !audienceOk && !fallback)
         return { ok: false, reason: 'wrong-audience' };
     if (!hasBound && !d.unboundOpen)
@@ -179,6 +198,10 @@ export async function verifyOriginClaim(req, d) {
     // signature is accepted for migration compatibility but remains unbound.
     let bound = false;
     const signedBy = (card) => {
+        if (hasBodySig) {
+            bound = audienceOk && verifies(card, bodyBoundCanonical(caller, callerUrl, ts, audience, req.method ?? '', pathOf(req.url ?? ''), digest), bodySig);
+            return bound;
+        }
         bound = audienceOk && verifies(card, boundCanonical(caller, callerUrl, ts, audience, req.method ?? '', pathOf(req.url ?? '')), boundSig);
         return bound || (fallback && verifies(card, unboundCanonical(caller, callerUrl, ts), unboundSig));
     };
@@ -187,7 +210,7 @@ export async function verifyOriginClaim(req, d) {
             return;
         d.onUnbound();
         if (hasBound)
-            d.onBoundMiss?.();
+            d.onBoundMiss?.({ caller, audience: originOf(audience) });
     };
     // gh#133: a CLI identity deposited HERE, decided from the deposit table
     // before any fetch (the CLI may reach its home through a proxy the host

package/lib/owner-settings.js

@@ -8,8 +8,39 @@
  * else; a missing entry is appended in the canonical short-id form.
  * @module @nelsonlongxiang/dsh-open-a2a-net/owner-settings
  */
+/** A label shaped like a routable address (`dsh/66abc2cf`, `zone/canvas/x`, `name/<16 hex>`) would pass for another
+ *  session in the directory and in `a2a-net teams <query>`; labels are display-only, so that shape is refused. */
+const ADDRESS_SHAPED = /^[A-Za-z0-9._-]+\/\S+$/;
+/** Shared validation for boot config and owner POST; labels are plain text, never handles or authority. */
+export function parseSeatNames(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length > 1024)
+        return undefined;
+    const entries = Object.entries(value);
+    if (entries.some(([id, name]) => !/^session-[a-zA-Z0-9-]{8,128}$/.test(id) || typeof name !== 'string' || name.trim() === '' || [...name.trim()].length > 64 || /[\p{Cc}\p{Cf}\u2028\u2029\ufffd]/u.test(name) || !/[^\p{Z}\p{C}\p{M}]/u.test(name) || ADDRESS_SHAPED.test(name.trim())))
+        return undefined;
+    return Object.fromEntries(entries.map(([id, name]) => [id, name.trim()]));
+}
+/** Boot config degrades entry-by-entry; owner POST remains all-or-nothing. Never echo label contents in warnings. */
+export function loadSeatNames(value, warn) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        warn('seatNames: ignored invalid map');
+        return {};
+    }
+    const kept = {};
+    let count = 0;
+    for (const [id, name] of Object.entries(value)) {
+        const entry = parseSeatNames({ [id]: name });
+        if (entry === undefined || count >= 1024) {
+            warn('seatNames: ignored invalid or over-cap entry');
+            continue;
+        }
+        Object.assign(kept, entry);
+        count += 1;
+    }
+    return kept;
+}
 /** The exact keys this module may touch, in wire order. */
-const KEYS = ['teamJoinAllowlist', 'teamScopeInfo', 'announce'];
+const KEYS = ['teamJoinAllowlist', 'teamScopeInfo', 'announce', 'seatNames'];
 export function applyOwnerSettings(patchYaml, changes) {
     const lines = patchYaml.split('\n');
     // Find the a2a entry: `- id: a2a` / `- id: 'a2a'` variants.
@@ -34,6 +65,8 @@ export function applyOwnerSettings(patchYaml, changes) {
         writes.push(`    teamScopeInfo: ${changes.teamScopeInfo ? 'true' : 'false'}`);
     if (changes.announce !== undefined)
         writes.push(`    announce: ${changes.announce ? 'true' : 'false'}`);
+    if (changes.seatNames !== undefined)
+        writes.push(`    seatNames: ${JSON.stringify(changes.seatNames)}`);
     if (writes.length === 0)
         return { yaml: patchYaml, restartNeeded };
     if (entryStart === -1) {
@@ -81,6 +114,10 @@ export function applyOwnerSettings(patchYaml, changes) {
                 if (write !== undefined) {
                     lines[j] = write;
                     found = true;
+                    // A map may have been authored as block YAML. Replace its nested rows too, not just the heading.
+                    if (key === 'seatNames')
+                        while (j + 1 < lines.length && (/^ {5,}\S/.test(lines[j + 1] ?? '') || /^\s*$/.test(lines[j + 1] ?? '')))
+                            lines.splice(j + 1, 1);
                 }
                 break;
             }

package/lib/peer-directory.js

@@ -109,7 +109,7 @@ export function peerDirectoryRows(card, peer, includeCanvas) {
     if (includeCanvas)
         for (const entry of advertisedCanvasTeams(card)) {
             const declared = rosterOf.get(entry.team);
-            rows.push({ team: entry.team, session: card.session, name: entry.name, description: 'canvas team', origin, via: peer, ...(legacy ? { legacy } : {}), ...(declared !== undefined && declared.length > 0 ? { teams: declared } : {}), canvasMembers: entry.members.filter(ref => !publishedSessions.has(ref)) });
+            rows.push({ team: entry.team, session: card.session, name: entry.name, description: 'canvas team', kind: 'canvas', owner: peer, memberCount: entry.members.length, origin, via: peer, ...(legacy ? { legacy } : {}), ...(declared !== undefined && declared.length > 0 ? { teams: declared } : {}), canvasMembers: entry.members.filter(ref => !publishedSessions.has(ref)) });
         }
     return rows;
 }

package/lib/peer-link-display.js

@@ -0,0 +1,15 @@
+export function peerLinkDisplay(peerUrl, d) {
+    const { card } = d;
+    if (card === undefined)
+        return { link: 'stranger', verified: false };
+    const origin = (url) => { try {
+        return new URL(url).origin;
+    }
+    catch {
+        return '';
+    } };
+    const peerOrigin = origin(peerUrl), ownOrigin = origin(d.ownUrl);
+    const bilateral = peerOrigin !== '' && ownOrigin !== '' && d.seeds.some(url => origin(url) === peerOrigin) && (card.peers ?? []).some(url => origin(url) === ownOrigin);
+    const exactMember = d.refs.some(ref => !d.ownHandles.has(ref) && (card.sessionTeams ?? []).some(row => row.team === ref) && !d.cards.some(other => other.publicKey !== card.publicKey && (other.sessionTeams ?? []).some(row => row.team === ref)));
+    return { link: bilateral || exactMember ? 'linked' : 'stranger', verified: true };
+}

package/lib/skill/references/cli.md

@@ -42,6 +42,10 @@ model tools.
   405 with an empty body. The fix is a host upgrade, not a retry.
 - `a2a-net revoke` deregisters early.
 
+## Team display names
+
+`a2a-net teams <query>` searches the owner-set seat label as well as the route handle; `--json` exposes the effective display name. Local rows prefer `seatName`, then the current title (`name`), then the legacy label. Only the human workbench owner panel/config can set `seatNames`; the CLI has no naming command.
+
 ## Tasks: ledger and host observability
 
 `a2a-net tasks --json` returns the existing `pending`, `dead`, and `archived` arrays plus `settlement` and `conservation` copied unchanged from `/__dsh_a2a/state`. These blocks include the lifetime `settlement.refusalsTotal`, refusal ring and mode, and the host conservation verdict/counters/duplicate ids. Older hosts omit a block they do not expose; the CLI does not manufacture zero counters or a passing verdict. Plain `tasks` appends a conservation line (`conserved`, `delta`) and a settlement line (`mode`, `refusalsTotal`, `offChain`) when the respective block exists.
@@ -117,9 +121,9 @@ Files do not go through session messages: use the file channel below, never JPFI
   - Reusing an id for a different message, or switching `--sync` on or off,
     is refused (exit 1): drop `--task` to send it as a new task.
   - `report` takes `--task` the same way.
-- Home-host forwarding is opt-in: `forwardDirect: true` forwards one hop only after a local target miss. H must not be isolated, the CLI must be online and sign a bound envelope, the inbound request must have no Guard, and the target must pass H’s sender scope.
+- From 0.6.38 home-host forwarding defaults on (`forwardDirect: true`); explicit `false` restores local-only delivery. It forwards one hop only after a local target miss. H must not be isolated, the CLI must be online and sign a bound envelope, the inbound request must have no Guard, and the target must pass H’s sender scope.
 - Both operators establish links: at A, put the CLI and B receiving member handles in an operator canvas; at B, link the CLI handle and pin its home to A. A remote canvas target requires A to directly link every advertised receiving member; a peer-org claim alone is insufficient for the return receipt.
-- B signs its auto-receipt as the member that did the work. Its destination prefers an online CLI household on that host (an owner-controlled fact); otherwise it returns only to the pinned home, never another directory advertiser. In the normal single-home setup it settles A’s single forwarded outbound row on-chain under `enforce` and enters the CLI mailbox (`a2a-net inbox`). `--sync` returns B’s final reply. A 15s transport-budget expiry is `-32005`; reconcile by task id rather than resend blindly.
+- B signs its auto-receipt as the member that did the work. Its destination prefers an online CLI household on that host (an owner-controlled fact); otherwise it returns only to the pinned home, never another directory advertiser. In the normal single-home setup it settles A’s single forwarded outbound row on-chain under `enforce` and enters the CLI mailbox (`a2a-net inbox`). `--sync` returns B’s final reply. The transport still has a 15s synchronous patience window, not a full model-turn budget. For forwarded or long work, prefer `a2a-net route <team> <message>` (async by default) then `a2a-net inbox --wait --renew`. A `--sync` transport expiry is `-32005`; the target still auto-receipts the original task after finishing. Reconcile by task id/inbox instead of treating a new direct pong as its receipt or resending blindly.
 - With forwarding off or any prerequisite missing, the original "No live DSH session node accepts team" error includes the reason it was not forwarded. Receiving hosts never forward the forwarded request again.
 - Admission: a deposited handle is a node fact of its home host (N3); that fact alone grants no remote scope or admission. Operator canvas membership and B’s home pin are still required. Global self-description is never a link.
 - `a2a-net report <message…>` is a one-way report to the host's process team.
@@ -165,9 +169,13 @@ Files do not go through session messages: use the file channel below, never JPFI
 
 ## Reading the host
 
+If configured enforcement is refused because old forwarded canvas debts lack receiver facts, the plugin stays online in observe. `tasks --json` preserves `settlement.mode` and `settlement.enforceRefused:{reason,blockers}`; tasks/status text also shows the refusal. This boot-time audit remains after reconciliation; a later owner-controlled reapplication may enable enforce once blockers are cleared. Configuration on disk is unchanged.
+
 `whoami`, `teams [query]`, `status`, `tasks`, `probe` read the home host's
 state face (key-gated on a keyed host). `--json` prints raw rows for
-`teams`, `tasks`, `probe`, `route`, `report`, `inbox` and `skills`.
+`whoami`, `teams`, `tasks`, `probe`, `route`, `report`, `inbox` and `skills`.
+
+`teams` includes local canvas and peerOrg rows with qualified route name, owner URL and memberCount; same names on different hosts stay separate. `whoami --json` is pure JSON and includes only canvases naming this CLI identity, local and remote. An unreadable optional state face reports canvasError/UNKNOWN, never falsely empty membership. Canvas failures retain the original refusal and add visible-directory not-found, owner prerequisites (including each missing direct receiver link), or conflicting owner candidates. Owner URLs do not require direct dialing or a home override and grant no admission.
 
 ## Local commands
 

package/lib/skill/references/pitfalls.md

@@ -24,7 +24,7 @@
   The `a2a-net` CLI (0.6.27+) is the supported exception: a DEPOSITED handle
   is routable on its home host and receives into its mailbox
   ([cli.md](cli.md)).
-- **"No live DSH session node accepts team" may name a forwarding prerequisite.** Direct delivery remains local by default. `forwardDirect: true` permits one hop only for an online, bound-signed local CLI, on a non-isolated home, with no inbound Guard and a target inside sender scope. A must link B’s receiving members; B must link the CLI and pin A as its home. Remote canvas org alone cannot authorize the receipt return path. Read the appended "not forwarded" reason; do not treat a missing link, expired deposit or already-forwarded request as a transport outage. The target host never forwards again.
+- **"No live DSH session node accepts team" may name a forwarding prerequisite.** From 0.6.38 `forwardDirect` defaults on; explicit `false` disables it. It permits one hop only for an online, bound-signed local CLI, on a non-isolated home, with no inbound Guard and a target inside sender scope. A must link B’s receiving members; B must link the CLI and pin A as its home. Remote canvas org alone cannot authorize the receipt return path. Read the appended "not forwarded" reason; do not treat a missing link, expired deposit or already-forwarded request as a transport outage. The target host never forwards again.
 - A sync route to a remote peer rides a 15s transport budget (a target on
   this host gets 180s) — both are shorter than many model turns. For
   anything that runs long, prefer `async: true` and the receipt contract.

package/lib/skill/references/setup.md

@@ -21,6 +21,10 @@ presenting the operator's gesture on the operator's behalf is exactly the
 | Version | `/__dsh_a2a/state` `version`, or the workbench header badge | the same version on every host you will link (0.6.28+) |
 | Clock | `date` on each host | NTP-synced: card signatures carry `expiresAt`, and the OriginClaim envelope allows ±5 min |
 
+## Human seat names
+
+The owner can open the workbench header ⚙, select a local session under “会话席位名”, and explicitly save a stable display name (up to 64 characters; a name shaped like a route address such as `dsh/66abc2cf` is refused so it cannot pass for another session). Empty input clears the label. The `seatNames` map is stored in the home patch layer and hot-applies; cards and the board prefer it over the session title, and `a2a_whoami` / `a2a-net teams <name>` expose it. It never changes the route handle, join state or admission. Agents must ask the owner rather than self-name: A2A tool arguments containing `seatName`/`seatNames` are refused; no naming model tool exists. The owner control API keeps its existing apiKey/loopback trust model, not a sandbox against local shell or config-file writers.
+
 ## 1. One host: sessions talking to each other
 
 **Owner:**
@@ -111,14 +115,11 @@ Do section 1 on both hosts first. Then the **owner**, on BOTH hosts:
 
 ## 3. Beyond direct peers (A cannot reach C)
 
-Host-to-host forwarding is **not shipped yet**. Today a delivery reaches only
-the host it is sent to:
-- `/a2a/direct` never relays.
-- A session's `a2a_route` dials the host that publishes the team.
-- #57 Plan A (host forwarding) is designed. Its prerequisite #60 hop budget
-  has landed at ingress.
+Home-host one-hop forwarding shipped in 0.6.34 and defaults **on from 0.6.38**. Explicit `forwardDirect: false` restores local-only CLI delivery. It only follows a local miss for a bound-signed, online CLI deposited on that home, inside the unchanged sender scope. A must directly link B's receiving member (all advertised potential receivers for a canvas), and B must link the CLI and pin A as home. The home must not be isolated and any inbound Guard prevents a second forward. The outbound hop budget remains DEFAULT-1. No links are auto-created or relaxed.
+
+Long forwarded work should use async `route` plus `inbox --wait --renew`, not expect a 15s `--sync` transport window to cover an entire model turn. A late final still produces the original task's receipt, and the forwarded row keeps selected-peer receiver facts for enforced settlement.
 
-Until forwarding ships, pick one:
+Other connectivity options (not authority bypasses):
 
 1. **Make it a peer pair.** Open a tunnel or port-forward so A reaches C,
    then do section 2 for A↔C. This is the simplest and keeps receipts
@@ -135,8 +136,7 @@ Until forwarding ships, pick one:
 ## 4. Callers outside a session
 
 Scripts and terminals use the `a2a-net` CLI: deposit on ONE home host, read
-a mailbox, no wake. The same rule applies: the CLI reaches only teams on its
-home host. See [cli.md](cli.md).
+a mailbox, no wake. The home can forward eligible requests one hop under section 3; an online deposit alone grants no remote scope. See [cli.md](cli.md).
 
 ## 5. Symptom → step