@nelsonlongxiang/dsh-open-a2a-net 0.6.33 → 0.6.35

package/lib/index.js

@@ -34,6 +34,9 @@ import { LayoutStore } from "./layout-store.js";
 import { JoinedSessions } from "./joined-store.js";
 import { ExposureStore } from "./exposure-store.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 { TeamMembershipStore } from "./team-store.js";
 import { PeerStore } from "./peer-store.js";
 import { SelfReferralFilter } from "./self-suppress.js";
@@ -42,11 +45,12 @@ import { formatReceipt, parseReceipt, taskIdRefusal } from "./receipt.js";
 import { runReceiptLadder } from "./receipt-ladder.js";
 import { IdempotencyStore, WIRE_ERROR_IDEMPOTENCY_CONFLICT, WIRE_ERROR_REPLAY_REJECTED, peerPayloadFingerprint } from "./idempotency-store.js";
 import { createFloodGuard } from "./flood-guard.js";
+import { createQueueGuard, DEFAULT_TARGET_QUEUE_CAP, queueFullRefusal, 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 { AuthObserver } from "./auth-observer.js";
-import { allowlistVersion, authorizationRef, buildAuthorization, callerAdmission, localCandidateAdmission, canonicalAllowlist, judgeSettlement, joinedFaceAdmission, refusalOf, sameZoneAdmission } from "./task-auth.js";
+import { allowlistVersion, authorizationRef, buildAuthorization, callerAdmission, localCandidateAdmission, canonicalAllowlist, judgeSettlement, joinedFaceAdmission, refusalOf, sameZoneAdmission, recheckRemoteCliAuthorization } from "./task-auth.js";
 import s from '@deepseek-ai/schemastery';
 import { MessageId } from '@deepseek-ai/dsh-llm';
 import { SessionId } from '@deepseek-ai/dsh-session';
@@ -83,6 +87,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),
     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([]),
@@ -179,6 +184,8 @@ export const Config = s.object({
      * t-mt6nd0sq-hxuhj6). 0 disables the nudge entirely.
      */
     asyncNudgeDelayMs: s.number().default(120_000),
+    /** gh#224: at most this many receipt-owing tasks queue for one target; the next is refused (-32009). 0 disables. */
+    targetQueueCap: s.number().default(DEFAULT_TARGET_QUEUE_CAP),
     stateColdRowsTtlMs: s.number().default(5_000),
     cardCacheTtlMs: s.number().default(60_000),
     cardCacheNegativeTtlMs: s.number().default(30_000),
@@ -755,7 +762,10 @@ export function apply(ctx, config) {
             // message that still echoes a pending task id means the peer
             // demonstrably responded to it, which settles the debt even when the
             // receipt formality never rode the reply.
-            const echoed = taskLedger.resolveEcho(message, judge);
+            // #125 (owner data 2026-11-03: two production rows settled by a relay and by another task's receipt):
+            // an echo is weak evidence, so under observe it is judged as enforce — only an on-chain settler's echo
+            // settles. Formal receipt headers keep observing; settlementAuth 'off' still judges nothing.
+            const echoed = taskLedger.resolveEcho(message, judge !== undefined && !judge.enforce ? { ...judge, enforce: true } : judge);
             if (echoed.length > 0) {
                 logger.info(`a2a: ${String(echoed.length)} pending task(s) settled by content echo (${echoed.join(', ')})`);
             }
@@ -799,6 +809,8 @@ export function apply(ctx, config) {
     // refused-but-idempotent, same-key different-payload answers conflict.
     const idempotencyStore = new IdempotencyStore(join(home, 'a2a', 'idempotency.json'));
     const refuseIfFlooded = createFloodGuard(idempotencyStore, recordActivity);
+    const ownTask = (taskId) => taskLedger.list().some(r => r.taskId === taskId) || taskLedger.archive().some(r => r.taskId === taskId);
+    const refuseIfQueueFull = createQueueGuard(() => taskLedger.list(), () => config.targetQueueCap, ownTask, idempotencyStore, recordActivity);
     // Unmasked-identity suppression: gossip mirrors peer lists back and forth,
     // so a URL whose fetch just proved it serves this node — or an already
     // tracked node (an alias spelling) — keeps coming home as an inbound
@@ -1639,7 +1651,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, 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, 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,
                 get cardCache() { return cardCache; },
                 get remoteRowsCache() { return remoteRowsCache; },
@@ -1771,7 +1783,7 @@ export function apply(ctx, config) {
                         // deposit stays as an OFFLINE row (tombstone) so the board keeps
                         // the member card grayed-but-present and canvas refs never
                         // dangle silently; re-publish (same handle) un-tombstones.
-                        ...cliDeposits.directoryRows().map(row => exposureRow(row.team, { name: row.name, description: row.description })),
+                        ...cliDeposits.directoryRows().map(row => exposureRow(row.team, { name: row.name, description: row.description, offline: row.offline })),
                     ];
                     const memberships = teamMemberships.list().flatMap(entry => entry.teams.map(team => ({ node: `${config.team}/${id8(entry.session)}`, team })));
                     const body = JSON.stringify({
@@ -2139,7 +2151,7 @@ export function apply(ctx, config) {
             }
             return { ok: false, error: 'No live DSH agent is available to accept this message.' };
         }
-        return { ok: false, error: wake.kind === 'no-face' ? noWakeFaceText(team) : wake.kind === 'archived' ? archivedColdMatchText(team) : noColdMatchText(team) };
+        return { ok: false, ...(wake.kind === 'no-match' ? { localMiss: true } : {}), error: wake.kind === 'no-face' ? noWakeFaceText(team) : wake.kind === 'archived' ? archivedColdMatchText(team) : noColdMatchText(team) };
     }
     /**
      * Steer one direct route request into one named agent and resolve with its
@@ -2382,6 +2394,7 @@ export function apply(ctx, config) {
         },
         liveNodeIds: () => [...sessionNodes.values()].map(agent => String(agent.id)),
         cliDeposited: handle => cliDeposits.get(handle) !== undefined,
+        cliHomeOf: handle => canvasStore.cliHomeOf(handle),
     };
     /** W1/W2 shared-team admission (see sameZoneAdmission in src/task-auth.ts). */
     function sameZoneSharedTeamRefusal(caller, targetTeam) {
@@ -2393,8 +2406,8 @@ export function apply(ctx, config) {
         return verdict === undefined ? undefined : refusalOf(verdict);
     }
     /** Inbound admission with the rule and shared teams that admitted the caller (gh#114 S1). */
-    function a2aCallerAdmission(caller, targetTeam) {
-        return callerAdmission(admissionRecords, caller, targetTeam);
+    function a2aCallerAdmission(caller, targetTeam, cliProof) {
+        return callerAdmission(admissionRecords, caller, targetTeam, cliProof);
     }
     function a2aCallerRefusal(caller, targetTeam) {
         return refusalOf(a2aCallerAdmission(caller, targetTeam));
@@ -2418,6 +2431,7 @@ export function apply(ctx, config) {
             // Local members by their handle (design §2.3), remote refs as they are stored.
             canvas: canvasStore.list().map(name => [canvasTeamOf(name), canvasStore.membersOf(name).map(m => (m.includes('/') ? m : handle(m)))]),
             cli: cliDeposits.list().map(row => row.handle),
+            cliHome: canvasStore.pinnedCliHomes(),
             links: config.peers.map(peer => { try {
                 return new URL(peer).origin;
             }
@@ -2443,7 +2457,7 @@ export function apply(ctx, config) {
             cause,
             rows: () => taskLedger.list(),
             // A local-candidate record (#139) is judged as the local candidate admits; every other one by the wire face.
-            judge: (caller, target, ingress) => (ingress === 'local' ? localCandidateAdmission(admissionRecords, caller, target) : callerAdmission(admissionRecords, caller, target)),
+            judge: (caller, target, ingress, auth) => auth.admission_rule === 'remote-ref-cli' ? recheckRemoteCliAuthorization(admissionRecords, auth) : (ingress === 'local' ? localCandidateAdmission(admissionRecords, caller, target) : callerAdmission(admissionRecords, caller, target)),
         });
         if (entry === undefined)
             return;
@@ -2539,6 +2553,8 @@ export function apply(ctx, config) {
             joinedSessions,
             idempotencyStore,
             verifyOriginClaim,
+            remoteCliProof,
+            forwardDirect: request => forwardDirect(request),
             callerLinkedToThisHost, get ownCardUrl() { return ownCardUrl; },
             recordActivity,
             bumpLegacyInbound: () => { legacyInboundCount += 1; },
@@ -2551,6 +2567,7 @@ export function apply(ctx, config) {
             readSessionLogTail,
             taskLedger,
             refuseIfFlooded,
+            refuseIfQueueFull,
             settleAndAnnounce,
             touchWakeDemand: () => { lastWakeDemandAt = Date.now(); },
             session,
@@ -2876,6 +2893,55 @@ export function apply(ctx, config) {
         }
         return { link: linked ? 'linked' : 'stranger', verified };
     }
+    async function freshCliHomeCards() {
+        return await mapBounded(peerStore.list(), 6, async (url) => {
+            // A failed read cannot prove a tracked host is unlinked (especially after a cold boot).
+            // Conservatively leave automatic ownership unknown; explicit fresh choices still work.
+            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' };
+        });
+    }
+    async function cliHomeForAdd(handle, requested) {
+        const localHousehold = () => cliDeposits.directoryRows().some(row => row.team === handle);
+        if (localHousehold())
+            return decideCliHome(handle, requested, [], true);
+        return decideCliHome(handle, requested, CLI_HANDLE_RE.test(handle) ? await freshCliHomeCards() : [], localHousehold());
+    }
+    async function cliHomeOptions(handle) {
+        const locallyHeld = () => cliDeposits.directoryRows().some(row => row.team === handle);
+        if (locallyHeld())
+            return cliHomeChoices(handle, [], true);
+        return cliHomeChoices(handle, await freshCliHomeCards(), locallyHeld());
+    }
+    /** Remote CLI admission never trusts a retained stale cache entry after a failed home read. */
+    async function remoteCliProof(handle, claim) {
+        const home = canvasStore.cliHomeOf(handle);
+        if (home === undefined || !claim.bound || claim.cli === true || !isRootOriginUrl(claim.callerUrl))
+            return undefined;
+        if (new URL(claim.callerUrl).origin !== home)
+            return undefined;
+        for (const url of peerStore.list()) {
+            try {
+                if (new URL(url).origin !== home)
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const card = await fetchPeerCard(url);
+            if (card === undefined || card.publicKey !== claim.card.publicKey)
+                continue;
+            cardCache.set(url, { at: Date.now(), card });
+            if (peerLinkState(url).link !== 'linked')
+                continue;
+            const row = card.sessionTeams?.find(item => item.team === handle);
+            if (row !== undefined)
+                return { origin: home, viaUrl: claim.callerUrl, bound: true, online: row.offline === false };
+        }
+        return { origin: home, viaUrl: claim.callerUrl, bound: true, online: false };
+    }
     function cachedCardFetch(url) {
         const hit = cardCache.get(url);
         const now = Date.now();
@@ -3217,6 +3283,22 @@ export function apply(ctx, config) {
      * caller label — the "能发即能收" invariant: whatever it addresses can
      * answer it with one route.
      */
+    const forwardDirect = createDirectForward({
+        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 }),
+        candidates: async (team, failures, caller) => { const fetch = memoizedCardFetch(); return { urls: await directoryPeerCandidates(fetch, team, failures, { id: caller, handle: caller }), card: fetch }; },
+        dispatch: (url, request, guard) => dispatchPeerCandidate(url, request.team, request.message, request.contextId, new AbortController().signal, request.caller, request.noWait, request.taskId, request.caller, guard),
+        ledger: taskLedger, activity: (team, peer, ok) => recordActivity('fwd', team, peer, ok),
+    });
+    const senderScopeRecords = {
+        zone: config.team, id8, teamsOf: id => teamMemberships.teamsOf(id), membersOf: team => teamMemberships.membersOf(team),
+        canvasNames: () => canvasStore.list(), canvasMembers: name => canvasStore.membersOf(name), canvasTeam: canvasTeamOf,
+        peerOrgs: function* () { for (const hit of cardCache.values())
+            if (hit.card?.canvasOrg)
+                yield hit.card.canvasOrg; },
+        warmPeers: () => mapBounded(resolutionPeers(), SWEEP_CONCURRENCY, cachedCardFetch),
+    };
     async function routeTrunk(args, agent, signal, hostCaller) {
         // Fix ③ (S4 audit): host-side calls carry no agent identity — every one
         // lands in the team audit ring, and the owner can flip the gate from
@@ -3252,62 +3334,11 @@ export function apply(ctx, config) {
             }
             catch { /* no initiator in this fiber */ }
             if (!initiator) {
-                const callerTeams = teamMemberships.teamsOf(scopeCaller);
-                const team = String(args.team ?? '').trim();
-                const sharedRoster = callerTeams.some(roster => teamMemberships.membersOf(roster).some(id => `${config.team}/${id8(id)}` === team));
-                // gh#71: the SHARED-CANVAS basis and the warm cache's peer-org
-                // basis (an org entry naming BOTH the caller and the target
-                // handle) count as declared here too — the same link the
-                // admission core honors on the receiving side; without this the
-                // tool face refused routes the canvas itself had authorized.
-                // Canvas members mix two shapes: LOCAL sessions sit by session
-                // id, cross-host members by zone/id8 handle — match either.
                 const callerHandle = `${config.team}/${id8(scopeCaller)}`;
                 scopedCanvasCaller = { id: scopeCaller, handle: callerHandle };
-                // gh#45 末修 (66abc2cf defect): a CANVAS GROUP NAME target
-                // (`<team>/canvas/<name>`) never matches member handles — a
-                // whole-group dispatch from a group member was refused. The
-                // group's own team handle (canvasTeamOf(name)) is the match
-                // (the caller sits in the very group being addressed).
-                const sharedCanvas = canvasStore.list().some(name => {
-                    const members = canvasStore.membersOf(name);
-                    const inGroup = members.includes(scopeCaller) || members.includes(callerHandle);
-                    return inGroup ? members.includes(team) || canvasTeamOf(name) === team : false;
-                });
-                // A direct group route must not require a prior directory call. Fetch
-                // only the same eligible peers as resolution; then apply the
-                // unchanged sender/receiver admission rules to their verified cards.
-                if (team.includes('/canvas/') && !sharedCanvas && !callerTeams.includes(team))
-                    await mapBounded(resolutionPeers(), SWEEP_CONCURRENCY, cachedCardFetch);
-                let orgShared = false;
-                for (const cached of cardCache.values()) {
-                    const org = cached.card?.canvasOrg;
-                    if (!Array.isArray(org))
-                        continue;
-                    for (const e of org) {
-                        if (typeof e.team !== 'string' || e.team === '' || !Array.isArray(e.members))
-                            continue;
-                        const inOrg = e.members.includes(scopeCaller) || e.members.includes(callerHandle);
-                        if (inOrg && (e.members.includes(team) || e.team === team)) {
-                            orgShared = true;
-                            break;
-                        }
-                    }
-                    if (orgShared)
-                        break;
-                }
-                if (callerTeams.length === 0 && !sharedRoster && !sharedCanvas && !orgShared) {
-                    return localRoute({
-                        ok: false,
-                        error: `team-scoped routing is on and this session (${id8(scopeCaller)}) has declared no team membership — a teamless node has no network. Declare one with a2a_team_join (subject to the owner's teamJoinAllowlist)`,
-                    });
-                }
-                if (!callerTeams.includes(team) && !sharedRoster && !sharedCanvas && !orgShared) {
-                    return localRoute({
-                        ok: false,
-                        error: `team-scoped routing is on: routing to "${team}" requires declared membership. This session's teams: ${callerTeams.join(', ')}. a2a_team_join can declare it (subject to the owner's teamJoinAllowlist)`,
-                    });
-                }
+                const scope = await outboundScope(senderScopeRecords, scopeCaller, callerHandle, String(args.team ?? '').trim());
+                if (!scope.ok)
+                    return localRoute(scope);
             }
         }
         let callerSession = resolveCallerLabel({
@@ -3470,6 +3501,12 @@ export function apply(ctx, config) {
             recordActivity('out', team, callerSession ?? 'local', false);
             return { ok: false, error: idRefusal, code: -32000 };
         }
+        // gh#224: a full target queue refuses a same-host delivery as the wire face does (receipts, CLI mailboxes pass).
+        const queueRefusal = queueFullRefusal(taskLedger.list(), team, message, config.targetQueueCap, cliDeposits.get(team) !== undefined, ownTask);
+        if (queueRefusal !== undefined) {
+            recordActivity('out', team, callerSession ?? 'local', false);
+            return { ok: false, error: queueRefusal, code: WIRE_ERROR_QUEUE_FULL };
+        }
         const canvasName = parseCanvasTeamName(team);
         // Issue #41 shape note: the caller label is the WIRE form (<zone>/<id8>
         // or a session label) and quick-dispatch BORROWS a live session's team
@@ -3739,9 +3776,9 @@ export function apply(ctx, config) {
      * exactly like same-host ones; older peers that ignore the flag simply
      * keep the blocking wait (graceful degradation).
      */
-    async function dispatchPeerCandidate(url, team, message, contextId, signal, callerSession, asyncMode = false, taskIdFromCaller, callbackAddress) {
+    async function dispatchPeerCandidate(url, team, message, contextId, signal, callerSession, asyncMode = false, taskIdFromCaller, callbackAddress, guard) {
         const flight = beginRoute(team, url);
-        const result = await client.routeDirect(url, team, message, contextId, signal, callerSession, asyncMode, taskIdFromCaller, callbackAddress);
+        const result = await client.routeDirect(url, team, message, contextId, signal, callerSession, asyncMode, taskIdFromCaller, callbackAddress, guard);
         endRoute(flight);
         recordActivity('out', team, url, result.ok);
         // F1 half-transaction compensation (t-mth5gmxy): the client's 15s budget
@@ -3778,6 +3815,18 @@ export function apply(ctx, config) {
      * owner escalation actually fires for cross-node callback addresses.
      */
     async function dispatchAnywhere(team, message, callerSession, contextId, signal, asyncMode, taskId, peerCaller) {
+        // A local online household is an owner-established fact and receives locally.
+        // Otherwise only the pinned home may receive; never fall back to directory claims.
+        const cliReceipt = CLI_HANDLE_RE.test(team) && parseReceipt(message) !== null;
+        if (cliReceipt && cliDeposits.get(team) === undefined) {
+            const home = canvasStore.cliHomeOf(team);
+            if (home === undefined)
+                throw new Error(`CLI receipt home is not pinned for ${team}`);
+            const delivered = await dispatchPeerCandidate(home, team, message, contextId, signal, peerCaller ?? callerSession, asyncMode, taskId);
+            if (!delivered.ok)
+                throw new Error(`CLI receipt to pinned home failed: ${delivered.error}`);
+            return delivered;
+        }
         const local = await dispatchLocalCandidate(team, message, callerSession, contextId, signal, asyncMode, taskId);
         // A background send books no outbound row: its birth facts have no row to go on.
         if (taskId !== undefined)
@@ -3787,6 +3836,8 @@ export function apply(ctx, config) {
                 throw new Error(local.error);
             return local;
         }
+        if (cliReceipt)
+            throw new Error(`local CLI household expired before delivery to ${team}; directory fallback refused`);
         const failures = [];
         const candidates = await directoryPeerCandidates(memoizedCardFetch(), team, failures);
         if (candidates.length === 0) {
@@ -3844,7 +3895,8 @@ export function apply(ctx, config) {
         const cards = await mapBounded(peers, CANDIDATE_CONCURRENCY, async (peer) => ({ peer, card: await fetch(peer) }));
         // Check after fetching all cards: a seeded peer publishing the same id8
         // makes the caller handle ambiguous, so do not send a canvas payload.
-        const resolveLocal = scopedCanvasCaller === undefined ? undefined : localHandleResolver();
+        const sessions = scopedCanvasCaller === undefined ? undefined : localHandleResolver();
+        const resolveLocal = sessions === undefined ? undefined : (ref) => cliDeposits.get(ref) !== undefined ? ref : sessions(ref);
         const resolutions = await mapBounded(peers, CANDIDATE_CONCURRENCY, async (peer) => ({ peer, outcome: await resolveZone(fetch, peer, team) }));
         if (canvasTargetAmbiguous(cards.map(entry => entry.card), team, scopedCanvasCaller, resolveLocal, resolutions.some(entry => entry.outcome.ok))) {
             failures.push(`ambiguous: team "${team}" has conflicting owners, identities, or a colliding caller; no payload sent`);

package/lib/outbound-scope.js

@@ -0,0 +1,25 @@
+export async function outboundScope(r, id, handle, team) {
+    const teams = r.teamsOf(id);
+    const sharedRoster = teams.some(roster => r.membersOf(roster).some(member => r.zone + '/' + r.id8(member) === team));
+    const sharedCanvas = r.canvasNames().some(name => {
+        const members = r.canvasMembers(name);
+        return (members.includes(id) || members.includes(handle)) && (members.includes(team) || r.canvasTeam(name) === team);
+    });
+    if (team.includes('/canvas/') && !sharedCanvas && !teams.includes(team))
+        await r.warmPeers();
+    let orgShared = false;
+    for (const org of r.peerOrgs())
+        for (const row of org) {
+            if (typeof row.team !== 'string' || row.team === '' || !Array.isArray(row.members))
+                continue;
+            if ((row.members.includes(id) || row.members.includes(handle)) && (row.members.includes(team) || row.team === team)) {
+                orgShared = true;
+                break;
+            }
+        }
+    if (teams.length === 0 && !sharedRoster && !sharedCanvas && !orgShared)
+        return { ok: false, error: `team-scoped routing is on and this session (${r.id8(id)}) has declared no team membership — a teamless node has no network. Declare one with a2a_team_join (subject to the owner's teamJoinAllowlist)` };
+    if (!teams.includes(team) && !sharedRoster && !sharedCanvas && !orgShared)
+        return { ok: false, error: `team-scoped routing is on: routing to "${team}" requires declared membership. This session's teams: ${teams.join(', ')}. a2a_team_join can declare it (subject to the owner's teamJoinAllowlist)` };
+    return { ok: true };
+}

package/lib/queue-guard.js

@@ -0,0 +1,37 @@
+import { parseReceipt } from "./receipt.js";
+export const WIRE_ERROR_QUEUE_FULL = -32009;
+export const DEFAULT_TARGET_QUEUE_CAP = 3;
+/** How many receipt-owing tasks this host holds pending for `team`. */
+export function queuedFor(rows, team) {
+    return rows.filter(row => row.status === 'pending' && row.receiptExpected !== false &&
+        (row.direction === 'inbound' || row.peer === 'local') &&
+        (row.team === team || row.deliveredTo === team)).length;
+}
+/** The refusal text when `team`'s queue is full, else undefined. `cap <= 0` disables the guard. */
+export function queueFullRefusal(rows, team, message, cap, mailbox, ownTask) {
+    // A config without the key (old patch layer, test harness) gets the shipped default, not "no cap".
+    const limit = typeof cap === 'number' && Number.isFinite(cap) ? cap : DEFAULT_TARGET_QUEUE_CAP;
+    if (limit <= 0 || mailbox)
+        return undefined;
+    const receipt = parseReceipt(message);
+    if (receipt !== null && receipt.taskId !== '' && ownTask(receipt.taskId))
+        return undefined;
+    const queued = queuedFor(rows, team);
+    if (queued < limit)
+        return undefined;
+    return `target-queue-full (gh#224): "${team}" already has ${String(queued)} task(s) waiting for a receipt (cap ${String(limit)}) — nothing was delivered. Wait for a receipt from it (a2a inbox / a2a_tasks), or send again later with a NEW task id (this one is recorded as failed); do not resend in a loop. A task that never gets a receipt turns dead after taskStaleTtlMs and stops counting.`;
+}
+/** Wire-face adapter in the flood guard's shape: a refused fresh key is FAILED, not stranded pending. */
+export function createQueueGuard(rows, cap, ownTask, outcomes, recordActivity) {
+    return (caller, message, team, taskId, mailbox, res) => {
+        const error = queueFullRefusal(rows(), team, message, cap(), mailbox, ownTask);
+        if (error === undefined)
+            return false;
+        outcomes.recordOutcome(taskId, { status: 'failed', error });
+        recordActivity('in', team, caller, false);
+        const payload = JSON.stringify({ error, reason: 'target-queue-full', code: WIRE_ERROR_QUEUE_FULL, task_id: taskId, team, delivered: false, task_status: 'TASK_STATE_FAILED' });
+        res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+        res.end(payload);
+        return true;
+    };
+}

package/lib/response-fields.js

@@ -0,0 +1,27 @@
+/** Add structured fields to any JSON response exit and recompute its Content-Length. */
+export function withResponseFields(res, fields) {
+    const writeHead = res.writeHead.bind(res);
+    const end = res.end.bind(res);
+    let head;
+    res.writeHead = (status, headers) => {
+        head = { status, headers: { ...(headers ?? {}) } };
+        return res;
+    };
+    res.end = (body) => {
+        let out = body;
+        if (typeof body === 'string') {
+            try {
+                const parsed = JSON.parse(body);
+                if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed))
+                    out = JSON.stringify({ ...parsed, ...fields });
+            }
+            catch { /* not JSON: unchanged */ }
+        }
+        if (head !== undefined) {
+            if (out !== undefined && 'Content-Length' in head.headers)
+                head.headers['Content-Length'] = Buffer.byteLength(out);
+            writeHead(head.status, head.headers);
+        }
+        return end(out);
+    };
+}

package/lib/skill/references/cli.md

@@ -42,8 +42,14 @@ model tools.
   405 with an empty body. The fix is a host upgrade, not a retry.
 - `a2a-net revoke` deregisters early.
 
+## 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.
+
 ## Files (#91 file channel)
 
+Files do not go through session messages: use the file channel below, never JPFILE-PART/base64 chunks in `route`. Legacy part replies carry `advice.reason: use-file-channel` with the send commands; up to 16 compatible parts are still allowed, while over-limit transfers keep `-32008` / `file-parts-exceeded`. The hint alone does not mean rejection.
+
 - `a2a-net file send <path…> <team> [--note TEXT]` stages each file (≤64 MiB,
   ≤16 per send) on the home host by sha256, granted to `<team>` for 24h, and
   routes ONE message with one `[A2A file] v1 sha256=… size=… name=… from=<home>`
@@ -111,10 +117,11 @@ model tools.
   - 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.
-- Direct delivery does not relay: only teams on the home host are reachable.
-  A team on another host answers "No live DSH session node accepts team".
-- Admission: a deposited handle is a node fact of its home host (N3). It
-  carries no roster or canvas membership of its own.
+- 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.
+- 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.
+- 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.
 - A message that starts with `-` goes after `--`. Flag values never become
   part of the message.

package/lib/skill/references/pitfalls.md

@@ -9,6 +9,10 @@
 - **adopt-style revive only works for previously materialized sessions** —
   it is an idempotent revive, not a creation path.
 
+## Files
+
+- **Files do not go through session messages.** Use `a2a_file_send { paths, team }` (up to 16 files, 64 MiB each), then `a2a_file_fetch { ref }` on the received `[A2A file] v1 …` reference. CLI: `a2a-net file send <path…> <team>` and `a2a-net file fetch "<reference line>"`. Do not base64/chunk files into JPFILE-PART messages. During compatibility rollout, accepted legacy parts carry `advice.reason: use-file-channel`; over-limit parts still fail with `-32008` / `file-parts-exceeded` and the same advice. Do not resend rejected parts in a loop.
+
 ## Routing
 
 - **Do not blindly re-dispatch after a sync timeout.** -32005 means the
@@ -20,10 +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)).
-- **Direct delivery does not relay.** `POST /a2a/direct` only serves teams on
-  the host that receives it; a team on another host answers "No live DSH
-  session node accepts team". `a2a_route` resolves peers and forwards;
-  direct callers (the CLI included) must target their home host's teams.
+- **"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.
 - 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/routing.md

@@ -1,5 +1,9 @@
 # Routing deep-dive
 
+## Files use the file channel
+
+Files do not go through session messages. Send with `a2a_file_send { paths, team }` (up to 16 files, 64 MiB each), not `a2a_route` with file bytes or JPFILE-PART chunks. The receiver uses `a2a_file_fetch { ref }` with the `[A2A file] v1 …` line. CLI: `a2a-net file send <path…> <team>` / `a2a-net file fetch "<reference line>"`. One reference message carries the transfer; ordinary routing and receipt rules below apply to that message. Legacy parts still allowed by the transitional cap receive `advice.reason: use-file-channel`; this hint is not a refusal or a completion receipt.
+
 ## The receipt contract
 
 Every async route (`wait:false`) registers the task on the peer and returns