@nelsonlongxiang/dsh-open-a2a-net 0.6.41 → 0.6.43

package/lib/index.js

@@ -30,7 +30,7 @@ export function resolveCallerLabel(input) {
 }
 import { encodePublicKey, signCard, verifyCard } from "./card.js";
 import { GroupStore } from "./group-store.js";
-import { CanvasStore, canvasNameReserved, isRemoteMemberRef } from "./canvas-store.js";
+import { CanvasStore, canvasNameReserved, isRemoteMemberRef, legacyBareMember } 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";
@@ -53,7 +53,7 @@ import { createFloodGuard } from "./flood-guard.js";
 import { createQueueGuard, queueFullRefusal, QUEUE_FULL_NEXT, WIRE_ERROR_QUEUE_FULL } from "./queue-guard.js";
 import { resolveZone } from "./zone.js";
 import { registerA2aNetworkSkill } from "./skill-registration.js";
-import { isRootOriginUrl, sameMountedUrl, signOriginClaim, verifyOriginClaim as verifyOriginClaimOf } from "./origin-claim.js";
+import { isRootOriginUrl, sameMountedUrl, originClaimTeamWarning, signOriginClaim, verifyOriginClaim as verifyOriginClaimOf } from "./origin-claim.js";
 import { AuthObserver } from "./auth-observer.js";
 import { allowlistVersion, authorizationRef, buildAuthorization, callerAdmission, localCandidateAdmission, canonicalAllowlist, judgeSettlement, joinedFaceAdmission, refusalOf, sameZoneAdmission, recheckRemoteCliAuthorization } from "./task-auth.js";
 import { MessageId } from '@deepseek-ai/dsh-llm';
@@ -173,6 +173,9 @@ export function apply(ctx, config) {
     });
     // F4 slice: say the quiet part at boot instead of leaving the exposure to
     // be discovered from a ledger full of unexplained steering.
+    const teamWarning = originClaimTeamWarning(config.team);
+    if (teamWarning !== undefined)
+        logger.warn(teamWarning);
     const exposure = directDeliveryExposure(config.peers, config.apiKey);
     if (exposure.warning !== undefined)
         logger.warn(exposure.warning);
@@ -594,7 +597,7 @@ export function apply(ctx, config) {
     // Canvas teams: user-composed multi-member routing groups. A session node
     // may sit in many teams; routing to <team>/canvas/<name> resolves the
     // first live member or wakes the first cold one (member order = priority).
-    const canvasStore = new CanvasStore(join(home, 'a2a', 'canvas.json'));
+    const canvasStore = new CanvasStore(join(home, 'a2a', 'canvas.json'), { legacyBareMembers: config.canvasLegacyBareMembers !== false });
     // #91 file channel: the sender host's blob store (docs/design/file-channel.md).
     const blobStore = new BlobStore(join(home, 'a2a'));
     // Spatial presentation state for the full-page stage (contract v2).
@@ -915,7 +918,13 @@ export function apply(ctx, config) {
         for (const id of joinedSessions.list()) {
             if (!isArchived(id))
                 continue;
-            const ownHandle = ownCanvasHandleOf(id, true);
+            try {
+                revokeCanvasMember(id, 'archive');
+            }
+            catch (error) {
+                logger.error('canvas archive suspension failed: %s', String(error));
+                continue;
+            }
             sessionNodes.delete(id);
             // Sections come back at the next mount (re-publish) if this archived reading was transient; the row stays.
             nodeBinder.suspend(id);
@@ -925,9 +934,6 @@ export function apply(ctx, config) {
             // joined session matches"). Safety without the deletion: wake refuses
             // archived intents (:804), card assembly and the state cold rows filter
             // them, the reconciler skips them, and JOIN_CAP bounds the file.
-            canvasStore.dropMember(id);
-            if (ownHandle !== undefined)
-                canvasStore.dropMember(ownHandle);
             // S2 consistency: an archived node's roster declarations die with it
             // — a left node keeps no team membership.
             teamMemberships.dropSession(id);
@@ -958,7 +964,13 @@ export function apply(ctx, config) {
                     continue;
                 if (sessionNodes.has(id) || joinedSessions.has(id))
                     continue;
-                canvasStore.removeMember(name, id);
+                try {
+                    canvasStore.removeMember(name, id);
+                }
+                catch (error) {
+                    logger.error('canvas stale-member prune failed (%s/%s): %s', name, id, String(error));
+                    continue;
+                }
                 logger.info(`a2a: canvas team "${name}" dropped stale member ${id8(id)} (no live node, no join intent)`);
             }
         }
@@ -1001,7 +1013,7 @@ export function apply(ctx, config) {
      * @param includeArchived - count archived sessions too (the archive prune
      *   drops an archived session's own handle).
      */
-    function localHandleResolver(includeArchived = false) {
+    function localHandleResolver(includeArchived = false, count = false, legacyOverride = false) {
         const isArchived = includeArchived ? undefined : archivedSessionFilter();
         const byHandle = new Map();
         for (const id of new Set([...joinedSessions.list(), ...sessionNodes.keys()])) {
@@ -1018,7 +1030,20 @@ export function apply(ctx, config) {
                     published.add(row.team);
         }
         return (ref) => {
+            // #334 qualified member routing is deliberately deferred; this window is only legacy bare inference.
+            if (!legacyOverride && config.canvasLegacyBareMembers === false)
+                return undefined;
             const hits = byHandle.get(ref);
+            const collision = (hits?.length ?? 0) > 1 || (hits?.length === 1 && published.has(ref));
+            if (count && legacyBareMember(ref)) {
+                legacyInferenceResolutions++;
+                if (collision) {
+                    legacyCollisionWarnings++;
+                    if (legacyCollisionRecent.length >= 16)
+                        legacyCollisionRecent.shift();
+                    legacyCollisionRecent.push({ member: ref, at: Date.now() });
+                }
+            }
             return hits?.length === 1 && !published.has(ref) ? hits[0] : undefined;
         };
     }
@@ -1029,6 +1054,30 @@ export function apply(ctx, config) {
      * handle-stored membership must not outlive the session's consent).
      * @param id - the local session id (still joined when this is read).
      */
+    const canvasMigrationEpoch = new Date().toISOString();
+    let legacyInferenceResolutions = 0, legacyCollisionWarnings = 0;
+    const legacyCollisionRecent = [];
+    function revokeCanvasMember(id, reason, name) {
+        if (!joinedSessions.has(id) && !sessionNodes.has(id))
+            return false;
+        const bare = config.team + '/' + id8(id);
+        const inferred = localHandleResolver(true, false, true)(bare) === id ? bare : undefined;
+        const qualified = bare + '@' + ownCanvasFingerprint;
+        const sameId8 = new Set([...joinedSessions.list(), ...sessionNodes.keys()].filter(local => id8(local) === id8(id)));
+        const pinned = canvasStore.ownerKeyOf(qualified);
+        const proof = sameId8.size === 1 && (pinned === undefined || pinned === encodePublicKey(createPublicKey(nodePrivateKey))) ? qualified : undefined;
+        return canvasStore.revokeLocal(id, proof, inferred, reason, name);
+    }
+    function canvasMigrationState() {
+        const raw = canvasStore.list().flatMap(name => canvasStore.rawMembersOf(name).filter(legacyBareMember).map(member => ({ name, member })));
+        const resolve = localHandleResolver(false, false);
+        return { canvasLegacyBareMembers: config.canvasLegacyBareMembers !== false, epoch: canvasMigrationEpoch,
+            legacyBareMembers: raw.length,
+            legacyInferredMembers: raw.filter(r => canvasStore.membersOf(r.name).includes(r.member) && resolve(r.member) !== undefined).length,
+            legacyInferenceResolutions, legacyCollisionWarnings, legacyCollisionRecent: [...legacyCollisionRecent],
+            suspendedMembersCount: new Set(canvasStore.state().suspendedMembers.map(r => JSON.stringify([r.team, r.member]))).size,
+            ...canvasStore.state() };
+    }
     function ownCanvasHandleOf(id, includeArchived = false) {
         const handle = `${config.team}/${id8(id)}`;
         return localHandleResolver(includeArchived)(handle) === id ? handle : undefined;
@@ -1056,8 +1105,8 @@ export function apply(ctx, config) {
      * reading that depends on which peer cards are cached must not rewrite
      * the store (review of PR #151 P2-2).
      */
-    function canvasLocalMembersOf(name) {
-        const resolve = localHandleResolver();
+    function canvasLocalMembersOf(name, count = false) {
+        const resolve = localHandleResolver(false, count);
         return canvasStore.membersOf(name).map(id => (isRemoteMemberRef(id) ? resolve(id) ?? id : id));
     }
     /** The 8-char suffix of one agent's id. */
@@ -1108,7 +1157,7 @@ export function apply(ctx, config) {
     function canvasLiveAgent(name, skipId) {
         if (name === undefined)
             return undefined;
-        for (const id of canvasLocalMembersOf(name)) {
+        for (const id of canvasLocalMembersOf(name, true)) {
             if (id === skipId)
                 continue;
             const agent = sessionNodes.get(id);
@@ -1128,7 +1177,7 @@ export function apply(ctx, config) {
         if (name === undefined)
             return undefined;
         const isArchived = archivedSessionFilter();
-        return canvasLocalMembersOf(name).find(id => id !== skipId && joinedSessions.has(id) && !liveRoots.has(id) && isArchived?.(id) !== true);
+        return canvasLocalMembersOf(name, true).find(id => id !== skipId && joinedSessions.has(id) && !liveRoots.has(id) && isArchived?.(id) !== true);
     }
     /**
      * Human-facing node facts for one session: the session title (fallback:
@@ -1593,7 +1642,7 @@ export function apply(ctx, config) {
         whenWebServerSettled((webServer) => {
             // 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,
+                ctx, config, logger, home, session, lanIp, PLUGIN_VERSION, controlRoute, controlTrustedWithoutKey, readJsonBody, peerFetch, peerStore, peerLinkState, originClaimHeaders, refreshRemoteRows, joinedSessions, exposureStore, teamMemberships, cliDeposits, groupStore, canvasStore, revokeCanvasMember, canvasMigrationState, 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, enforceRefused,
                 get cardCache() { return cardCache; },
                 get remoteRowsCache() { return remoteRowsCache; },
@@ -1655,11 +1704,13 @@ export function apply(ctx, config) {
                 // MINIMAL discovery card.
                 handler: async (req, res) => {
                     const send = (named, body_) => {
-                        res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body_) });
+                        res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body_), 'Cache-Control': 'private, no-store' });
                         res.end(body_);
                         void named;
                     };
                     const claim = await verifyOriginClaim(req);
+                    // #312: signed discovery is a reduced face; it never requests a full-card callback.
+                    const discoveryOnly = new URL(req.url ?? '/', 'http://x').searchParams.get('discovery') === '1';
                     // W3 (#18 half-side, 0.6.25): a VERIFIED envelope proves the
                     // caller holds a real node key — it does not prove a relationship
                     // with THIS host. The full card (sessionTeams/rosters =
@@ -1670,14 +1721,17 @@ export function apply(ctx, config) {
                     // Interaction with the OriginClaim narrowing: the caller is a
                     // bare zone; linkage judges that zone face against our canvas
                     // remote refs, joined handles, and the caller card's peers.
-                    const named = claim.ok && callerLinkedToThisHost(claim.caller, claim.ok ? claim.callerUrl : '', claim.ok ? claim.card : undefined);
+                    const linkedCaller = claim.ok && callerLinkedToThisHost(claim.caller, claim.callerUrl, claim.card);
+                    const showPeers = claim.ok && (configuredSeedCaller(claim.callerUrl) || linkedCaller);
+                    const named = !discoveryOnly && linkedCaller;
                     // gh#7 G1 (review-seat R2 ruling): the card serves two faces.
                     // A NAMED caller — ?caller_session= or the X-A2A-Caller header in
                     // the zone or zone/id8 shape — gets the FULL card. An anonymous
                     // fetcher (or an invalid shape, fail-closed) gets the MINIMAL
-                    // card: name/team/session/capabilities/records/peers/signature
-                    // stay (discovery, gossip, delegation, capability negotiation
-                    // unbroken), while sessionTeams/teamMemberships/lanIp are
+                    // card: name/team/session/capabilities/records/signature stay.
+                    // #312/#324 F1: peers requires a verified caller that we explicitly seed
+                    // or already link; unrelated self-signed strangers get no topology.
+                    // Meanwhile sessionTeams/teamMemberships/lanIp are
                     // omitted — session membership and rosters are collaboration
                     // facts, not discovery facts. Named determination does NOT
                     // require a shared team: demanding roster symmetry before the
@@ -1733,7 +1787,8 @@ export function apply(ctx, config) {
                     const memberships = teamMemberships.list().flatMap(entry => entry.teams.map(team => ({ node: `${config.team}/${id8(entry.session)}`, team })));
                     const body = JSON.stringify({
                         ...currentCard,
-                        peers: peerStore.list(),
+                        // #324 F1: possession of an arbitrary self-signed identity is not a local relationship.
+                        ...(showPeers ? { peers: peerStore.list() } : {}),
                         ...(named && sessionTeams.length > 0 ? { sessionTeams } : {}),
                         ...(named && memberships.length > 0 ? { teamMemberships: memberships } : {}),
                         // gh#41 fleet planning (owner ruling: any peer composes and
@@ -2182,8 +2237,21 @@ export function apply(ctx, config) {
         boundMissRecent.unshift({ ...row, count: row.count + 1, lastAt: Date.now() });
         boundMissRecent.length = Math.min(boundMissRecent.length, 16);
     };
-    function verifyOriginClaim(req, options) {
-        return verifyOriginClaimOf(req, {
+    /** Our configured seeds anchor origin claims; mounted claims require exact mount matching. */
+    function configuredSeedCaller(callerUrl) {
+        return config.peers.some(peer => {
+            try {
+                return isRootOriginUrl(callerUrl) ? new URL(peer).origin === new URL(callerUrl).origin : sameMountedUrl(peer, callerUrl);
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    // #312: topology-only callbacks must never replace a full session/roster card cache entry.
+    const signedDiscoveryPeers = new Map();
+    async function verifyOriginClaim(req, options) {
+        const claim = await verifyOriginClaimOf(req, {
             cardCache,
             fetch: fetchImpl,
             audiences: [ownCardUrl, ...config.originClaimAudiences ?? []],
@@ -2195,6 +2263,32 @@ export function apply(ctx, config) {
             ...(options?.cli === true ? { cliDeposit: cliDepositCard } : {}),
             ...(options?.rawBody !== undefined ? { rawBody: options.rawBody } : {}),
         });
+        // #312: recover bilateral seed evidence from a signed, reduction-only card,
+        // never from a caller-selected unseeded URL and never recursively.
+        const discovery = new URL(req.url ?? '/', 'http://x').searchParams.get('discovery') === '1';
+        if (!discovery && claim.ok && claim.cli !== true && claim.card.peers === undefined && configuredSeedCaller(claim.callerUrl)) {
+            const discoveryKey = new URL(claim.callerUrl).href.replace(/\/$/, '');
+            const known = signedDiscoveryPeers.get(discoveryKey);
+            if (known !== undefined && known.key === claim.card.publicKey && known.expiresAt > Date.now() && Date.now() - known.at < config.cardCacheTtlMs)
+                return { ...claim, card: { ...claim.card, peers: known.peers } };
+            const target = claim.callerUrl.replace(/\/$/, '') + '/.well-known/agent-card.json?discovery=1';
+            try {
+                const response = await peerFetch(target, { method: 'GET', headers: peerRequestHeaders(target, 'GET'), redirect: 'manual', signal: AbortSignal.timeout(5_000) });
+                if (response.ok) {
+                    const verified = verifyCard(JSON.parse(await response.text()), Date.now());
+                    if (verified.ok && verified.card.publicKey === claim.card.publicKey && verified.card.team === claim.card.team) {
+                        if (verified.card.peers !== undefined) {
+                            signedDiscoveryPeers.set(discoveryKey, { at: Date.now(), expiresAt: verified.card.expiresAt, key: verified.card.publicKey, peers: verified.card.peers });
+                            if (signedDiscoveryPeers.size > 64)
+                                signedDiscoveryPeers.delete(signedDiscoveryPeers.keys().next().value);
+                        }
+                        return { ...claim, card: { ...claim.card, ...(verified.card.peers !== undefined ? { peers: verified.card.peers } : {}) } };
+                    }
+                }
+            }
+            catch { /* unavailable refresh keeps bilateral-link checks closed */ }
+        }
+        return claim;
     }
     /**
      * gh#133: the deposited card a CLI claim is judged by, or undefined when

package/lib/origin-claim.js

@@ -153,6 +153,10 @@ export function requestAudiences(req, configured, loopbackArrival = true) {
     return out;
 }
 const originClaimCallerShape = /^[a-z0-9-]+$/i;
+/** #312: explain unsupported host zone configuration without changing startup or signature policy. */
+export function originClaimTeamWarning(team) {
+    return originClaimCallerShape.test(team) ? undefined : 'a2a: configured host team contains invalid characters; OriginClaim cannot produce a verifiable host identity. Use ^[a-z0-9-]+$ (no slash).';
+}
 /**
  * Verify one request's envelope. Cheap refusals (shape, ts, audience,
  * closed window) answer before any card fetch; the card is then read from

package/lib/skill/SKILL.md

@@ -1,117 +1,117 @@
----
-name: a2a-network
-description: Use when a task needs cross-session or cross-node collaboration over the DSH A2A network — setting it up (install, config, apiKey, peers, canvas links for one host, two peers, or hosts that cannot reach each other), joining and teaming, routing work to remote teams and agents, reconciling receipts and the task ledger, and reading the A2A workbench (/__dsh_a2a_nexus/). Covers admission rules, the receipt contract, and the failure shapes that look like bugs but are contract semantics.
----
-
-# DSH A2A Network
-
-Drive the decentralized A2A network: sessions publish agent cards, join a
-membership layer, form canvas teams, and route work to each other through
-`a2a_route`. One plugin (`@nelsonlongxiang/dsh-open-a2a-net`) owns the whole
-surface on every node.
-
-## Objects
-
-- **Node** — one DSH host process exposing `/.well-known/agent-card.json` and
-  the `__dsh_a2a/state` face. Peers discover each other through cards.
-- **Session node** — a live DSH session on a node. Visibility follows
-  membership: an unjoined session is invisible to peer discovery AND refused
-  at the routing admission gate.
-- **Team** — a routable identity. Two kinds: the node's process team
-  (`<zone>/<id8>` from the session id) and canvas teams
-  (`<zone>/canvas/<name>`, user-composed multi-member groups).
-- **Task** — one routed round. Carries a task id, an idempotency fingerprint,
-  and a receipt contract.
-- **CLI identity** — a transient caller outside any session (the `a2a-net`
-  command, 0.6.27+): its own Ed25519 key and a handle `<name>/<16 hex>`,
-  deposited on ONE home host for up to 4h, with a mailbox instead of a
-  wakeable session. See [cli.md](references/cli.md).
-
-## Setting up
-
-Start with [setup.md](references/setup.md). It is a checked path for three
-network shapes:
-- **one host**: install, join the sessions, give them a shared team;
-- **two hosts that reach each other**: one shared `apiKey`, `announce` plus
-  peers seeded both ways, and a canvas team naming both handles;
-- **hosts that cannot reach each other**: host forwarding is not shipped
-  yet (#57), so tunnel or delegate per hop.
-
-The owner does the gestures (install, config, join, allowlist, canvas). The
-agent prepares the exact config and verifies each step with `a2a_whoami`,
-`a2a_probe`, `a2a_teams` and one round with a receipt.
-
-## Routing (a2a_route)
-
-```text
-a2a_route { team: "<zone>/<id8 or canvas name>", message, context_id?, async? }
-```
-
-- `async: true` delivers without waiting (`delivered:true` + task id); the
-  target routes a receipt — a message starting `[A2A receipt] task <id>` —
-  back to your team.
-- Sync (default) waits for the round's final answer. A target on this host
-  gets up to 180s; past that the tool answers the delivered shape
-  (`TASK_STATE_DELIVERED`) and the receipt contract carries the rest. A
-  remote peer's delivery rides a 15s transport budget; if it fires first, the
-  result is **-32005 DELIVERED-UNSETTLED**: the delivery landed and the peer
-  keeps executing. Either way, **never re-dispatch blindly** — reconcile via
-  the task id (the receipt, `a2a_status` activity, or `a2a_tasks`) instead.
-- Model tools cannot route to the bare process team (`<zone>` alone, the
-  host's own mailbox): target a session handle or a canvas team.
-- `context_id` from a previous reply continues that conversation.
-
-## Membership rules
-
-- An unjoined session has NO network: `a2a_route` and `a2a_teams` refuse it
-  (join gate), and discovery does not list it. The session that originates a
-  task is exempt from the gate.
-- Join through the GUI sidebar (A2A 网络) or the join gate prompt; leave
-  through the same surface. Membership is visible; leaving removes you from
-  discovery too.
-- Inbound deliveries from a caller with no `caller_session` are refused
-  (anonymous injection is a closed hole).
-
-## Reading the state
-
-`__dsh_a2a/state` (per node, key-gated like every control route) carries
-`sessions` (live/joined, with their teams), `canvas` (canvas teams; remote
-members show `remote: true`), `remote` (peer session rows with `origin` =
-node label + LAN IP and `via` = the peer URL), `activity` (routing ring),
-and the ledger: `tasks` (pending, each with `settleable`),
-`tasksStaleCount`, `tasksDead`, and `archived` (newest 64 settled rows, each
-with `outcome`, `endedBy` and `late`) plus `archivedCount` /
-`archivedSplit`. `sessionTeams` is a card field, not a state field. The A2A
-workbench (`/__dsh_a2a_nexus/`, merged responsive
-shell since 0.6.2 — the 2D planning board is the stage, directory / ledger /
-activity / plan ride a collapsible rail, narrow screens get a drawer)
-renders the same data for humans.
-
-## Failure shapes that are contract semantics
-
-- `-32000` with "declares no team membership" — the admission gate working
-  as designed; join (or route through a teamed member).
-- `-32000` with "caller_session is required" — the delivery had no caller
-  identity; the protocol contract requires it.
-- `-32005` — sync wait budget fired; delivery landed, reconcile the task id.
-- "No live DSH session node accepts team X" — no session node on the host
-  that received the delivery accepted the round. Either the target session is
-  not live/joined there, or X lives on ANOTHER host and the caller delivered
-  straight to this host's `/a2a/direct` (the `a2a-net` CLI does this):
-  direct delivery never relays to peers — `a2a_route` from a session does.
-- `[PATTERN_NO_MINT]` / `[ALLOWLIST_DENY]` on `a2a_team_join` — only an EXACT
-  allowlisted name joins; adding that name is the owner's act of creating
-  the team. `[CANVAS_TEAM]` — canvas membership is assigned in the workbench,
-  never by the roster tool.
-
-## Details
-
-- [setup.md](references/setup.md) — setup and checks: one host, two peers, beyond direct peers
-- [routing.md](references/routing.md) — receipts, idempotency, ledger anatomy
-- [discovery.md](references/discovery.md) — cards, peer boundary model, invisibility
-- [membership.md](references/membership.md) — join/leave, allowlist, canvas teams
-- [pitfalls.md](references/pitfalls.md) — operational pitfalls observed in production
-- [cli.md](references/cli.md) — the `a2a-net` CLI: deposit, mailbox, inbox hooks, limits
-- [collaboration.md](references/collaboration.md) — collaboration norm (Chinese): single-seat first, decide-then-report with no pre-authorization (a high-tier change needs one non-self node's review PASS on the same SHA), release tiers, stuck gates, credentials, receipts
-- [intake.md](references/intake.md) — intake node (Chinese): handling `workbench-event` deliveries from workbench-market — accept/decline/ask with a reason, open a GitHub issue on accept, write the decision back with the reply token
-- [router.md](references/router.md) — the chief's system prompt (Chinese), self-contained: route workbench events and owner requests to the right project's dev, order cross-project resource conflicts (it authorizes nothing since collaboration v1.18); immutable layer + self-kept mutable layer
+---
+name: a2a-network
+description: Use when a task needs cross-session or cross-node collaboration over the DSH A2A network — setting it up (install, config, apiKey, peers, canvas links for one host, two peers, or hosts that cannot reach each other), joining and teaming, routing work to remote teams and agents, reconciling receipts and the task ledger, and reading the A2A workbench (/__dsh_a2a_nexus/). Covers admission rules, the receipt contract, and the failure shapes that look like bugs but are contract semantics.
+---
+
+# DSH A2A Network
+
+Drive the decentralized A2A network: sessions publish agent cards, join a
+membership layer, form canvas teams, and route work to each other through
+`a2a_route`. One plugin (`@nelsonlongxiang/dsh-open-a2a-net`) owns the whole
+surface on every node.
+
+## Objects
+
+- **Node** — one DSH host process exposing `/.well-known/agent-card.json` and
+  the `__dsh_a2a/state` face. Peers discover each other through cards.
+- **Session node** — a live DSH session on a node. Visibility follows
+  membership: an unjoined session is invisible to peer discovery AND refused
+  at the routing admission gate.
+- **Team** — a routable identity. Two kinds: the node's process team
+  (`<zone>/<id8>` from the session id) and canvas teams
+  (`<zone>/canvas/<name>`, user-composed multi-member groups).
+- **Task** — one routed round. Carries a task id, an idempotency fingerprint,
+  and a receipt contract.
+- **CLI identity** — a transient caller outside any session (the `a2a-net`
+  command, 0.6.27+): its own Ed25519 key and a handle `<name>/<16 hex>`,
+  deposited on ONE home host for up to 4h, with a mailbox instead of a
+  wakeable session. See [cli.md](references/cli.md).
+
+## Setting up
+
+Start with [setup.md](references/setup.md). It is a checked path for three
+network shapes:
+- **one host**: install, join the sessions, give them a shared team;
+- **two hosts that reach each other**: one shared `apiKey`, `announce` plus
+  peers seeded both ways, and a canvas team naming both handles;
+- **hosts that cannot reach each other**: host forwarding is not shipped
+  yet (#57), so tunnel or delegate per hop.
+
+The owner does the gestures (install, config, join, allowlist, canvas). The
+agent prepares the exact config and verifies each step with `a2a_whoami`,
+`a2a_probe`, `a2a_teams` and one round with a receipt.
+
+## Routing (a2a_route)
+
+```text
+a2a_route { team: "<zone>/<id8 or canvas name>", message, context_id?, async? }
+```
+
+- `async: true` delivers without waiting (`delivered:true` + task id); the
+  target routes a receipt — a message starting `[A2A receipt] task <id>` —
+  back to your team.
+- Sync (default) waits for the round's final answer. A target on this host
+  gets up to 180s; past that the tool answers the delivered shape
+  (`TASK_STATE_DELIVERED`) and the receipt contract carries the rest. A
+  remote peer's delivery rides a 15s transport budget; if it fires first, the
+  result is **-32005 DELIVERED-UNSETTLED**: the delivery landed and the peer
+  keeps executing. Either way, **never re-dispatch blindly** — reconcile via
+  the task id (the receipt, `a2a_status` activity, or `a2a_tasks`) instead.
+- Model tools cannot route to the bare process team (`<zone>` alone, the
+  host's own mailbox): target a session handle or a canvas team.
+- `context_id` from a previous reply continues that conversation.
+
+## Membership rules
+
+- An unjoined session has NO network: `a2a_route` and `a2a_teams` refuse it
+  (join gate), and discovery does not list it. The session that originates a
+  task is exempt from the gate.
+- Join through the GUI sidebar (A2A 网络) or the join gate prompt; leave
+  through the same surface. Membership is visible; leaving removes you from
+  discovery too.
+- Inbound deliveries from a caller with no `caller_session` are refused
+  (anonymous injection is a closed hole).
+
+## Reading the state
+
+`__dsh_a2a/state` (per node, key-gated like every control route) carries
+`sessions` (live/joined, with their teams), `canvas` (canvas teams; remote
+members show `remote: true`), `remote` (peer session rows with `origin` =
+node label + LAN IP and `via` = the peer URL), `activity` (routing ring),
+and the ledger: `tasks` (pending, each with `settleable`),
+`tasksStaleCount`, `tasksDead`, and `archived` (newest 64 settled rows, each
+with `outcome`, `endedBy` and `late`) plus `archivedCount` /
+`archivedSplit`. `sessionTeams` is a card field, not a state field. The A2A
+workbench (`/__dsh_a2a_nexus/`, merged responsive
+shell since 0.6.2 — the 2D planning board is the stage, directory / ledger /
+activity / plan ride a collapsible rail, narrow screens get a drawer)
+renders the same data for humans.
+
+## Failure shapes that are contract semantics
+
+- `-32000` with "declares no team membership" — the admission gate working
+  as designed; join (or route through a teamed member).
+- `-32000` with "caller_session is required" — the delivery had no caller
+  identity; the protocol contract requires it.
+- `-32005` — sync wait budget fired; delivery landed, reconcile the task id.
+- "No live DSH session node accepts team X" — no session node on the host
+  that received the delivery accepted the round. Either the target session is
+  not live/joined there, or X lives on ANOTHER host and the caller delivered
+  straight to this host's `/a2a/direct` (the `a2a-net` CLI does this):
+  direct delivery never relays to peers — `a2a_route` from a session does.
+- `[PATTERN_NO_MINT]` / `[ALLOWLIST_DENY]` on `a2a_team_join` — only an EXACT
+  allowlisted name joins; adding that name is the owner's act of creating
+  the team. `[CANVAS_TEAM]` — canvas membership is assigned in the workbench,
+  never by the roster tool.
+
+## Details
+
+- [setup.md](references/setup.md) — setup and checks: one host, two peers, beyond direct peers
+- [routing.md](references/routing.md) — receipts, idempotency, ledger anatomy
+- [discovery.md](references/discovery.md) — cards, peer boundary model, invisibility
+- [membership.md](references/membership.md) — join/leave, allowlist, canvas teams
+- [pitfalls.md](references/pitfalls.md) — operational pitfalls observed in production
+- [cli.md](references/cli.md) — the `a2a-net` CLI: deposit, mailbox, inbox hooks, limits
+- [collaboration.md](references/collaboration.md) — collaboration norm (Chinese): single-seat first, decide-then-report with no pre-authorization (a high-tier change needs one non-self node's review PASS on the same SHA), release tiers, stuck gates, credentials, receipts
+- [intake.md](references/intake.md) — intake node (Chinese): handling `workbench-event` deliveries from workbench-market — accept/decline/ask with a reason, open a GitHub issue on accept, write the decision back with the reply token
+- [router.md](references/router.md) — the chief's system prompt (Chinese), self-contained: route workbench events and owner requests to the right project's dev, order cross-project resource conflicts (it authorizes nothing since collaboration v1.18); immutable layer + self-kept mutable layer