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

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),
@@ -799,6 +806,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 +1648,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 +1780,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 +2148,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 +2391,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 +2403,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 +2428,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 +2454,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 +2550,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 +2564,7 @@ export function apply(ctx, config) {
             readSessionLogTail,
             taskLedger,
             refuseIfFlooded,
+            refuseIfQueueFull,
             settleAndAnnounce,
             touchWakeDemand: () => { lastWakeDemandAt = Date.now(); },
             session,
@@ -2876,6 +2890,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 +3280,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 +3331,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 +3498,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 +3773,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 +3812,17 @@ 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.
+        if (CLI_HANDLE_RE.test(team) && parseReceipt(message) !== null && 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)
@@ -3844,7 +3889,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/skill/references/cli.md

@@ -111,10 +111,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

@@ -20,10 +20,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/task-auth.js

@@ -13,6 +13,8 @@
  * @module @nelsonlongxiang/dsh-open-a2a-net/task-auth
  */
 import { createHash } from 'node:crypto';
+import { CLI_HANDLE_RE } from "./cli-deposit.js";
+import { cliHomeOrigin } from "./cli-home.js";
 /** Every rule's basis — the mapping the authorization record stores beside the rule. */
 export const VIA_OF = {
     'scope-off': 'open',
@@ -22,6 +24,7 @@ export const VIA_OF = {
     'canvas-shared': 'canvas-member',
     'remote-ref-samezone': 'canvas-member',
     'remote-ref-foreign': 'canvas-member',
+    'remote-ref-cli': 'canvas-member',
     'peer-org': 'peer-org',
     'node-fact': 'joined-session',
     'cli-deposit': 'cli-deposit',
@@ -209,7 +212,7 @@ export function localCandidateAdmission(r, callerSession, targetTeam) {
     return joinedFaceAdmission(r, callerSession, targetTeam) ?? admitted('local-exempt');
 }
 /** Inbound admission for the peer faces (/a2a/direct, /a2a/log): caller_session is the contract. */
-export function callerAdmission(r, caller, targetTeam) {
+export function callerAdmission(r, caller, targetTeam, cliProof) {
     if (!r.teamScopeRouting)
         return admitted('scope-off');
     if (caller === '') {
@@ -227,6 +230,21 @@ export function callerAdmission(r, caller, targetTeam) {
             return admitted('remote-ref-foreign', basis);
         return refused(`caller "${caller}" has no operator-established link on this node — cross-host admission requires a canvas remote membership this host's operator added (N3/N4: the caller's own card claims are self-description, not links). Ask this host's operator to add the member in the A2A workbench, or route through a linked member.`);
     }
+    // A foreign CLI handle is never a free-form node fact: its operator link,
+    // pinned home, bound signer, and fresh online row must ALL hold.
+    if (CLI_HANDLE_RE.test(caller) && !r.cliDeposited(caller)) {
+        const basis = r.canvasNames().filter(name => r.canvasRemoteMembersOf(name).includes(caller)).map(name => r.canvasTeamOf(name));
+        if (basis.length === 0)
+            return refused(`remote CLI ${caller} has no operator-established canvas link`);
+        const home = r.cliHomeOf?.(caller);
+        if (home === undefined)
+            return refused(`remote CLI ${caller} home is not pinned`);
+        if (cliProof?.bound !== true || cliHomeOrigin(cliProof.origin) !== home || cliHomeOrigin(cliProof.viaUrl) !== home)
+            return refused(`remote CLI ${caller} signer does not match pinned home`);
+        if (cliProof.online !== true)
+            return refused(`remote CLI ${caller} is offline or home card could not be read`);
+        return admitted('remote-ref-cli', basis);
+    }
     // Free-form label: only this host's own node facts (V3).
     if (r.joined().includes(caller))
         return admitted('node-fact');
@@ -241,6 +259,18 @@ export function callerAdmission(r, caller, targetTeam) {
         return admitted('cli-deposit');
     return refused(`caller_session "${caller}" matches no node fact on this host (joined session id, live node label, or deposited CLI handle) — free-form caller labels are self-description and are not admissible (N3). Pass caller_session as <zone>/<id8> with an operator-established link.`);
 }
+/** Revalidate only mutable operator authority, not already-verified birth-time identity or liveness. */
+export function recheckRemoteCliAuthorization(r, auth) {
+    if (!r.teamScopeRouting)
+        return admitted('scope-off');
+    const basis = r.canvasNames().filter(name => r.canvasRemoteMembersOf(name).includes(auth.caller)).map(name => r.canvasTeamOf(name));
+    if (basis.length === 0)
+        return refused(`remote CLI ${auth.caller} has no operator-established canvas link`);
+    const home = r.cliHomeOf?.(auth.caller);
+    if (home === undefined || home !== cliHomeOrigin(auth.carrier_url))
+        return refused(`remote CLI ${auth.caller} pinned home changed`);
+    return admitted('remote-ref-cli', basis);
+}
 const sortedUnique = (values) => [...new Set(values)].sort();
 const pairKey = (pair) => JSON.stringify(pair);
 /**
@@ -265,6 +295,7 @@ export function canonicalAllowlist(inputs) {
         roster,
         canvas,
         cli: sortedUnique(inputs.cli),
+        ...(inputs.cliHome !== undefined && inputs.cliHome.length > 0 ? { cliHome: [...new Map(inputs.cliHome.map(p => [JSON.stringify(p), p])).values()].sort((a, b) => pairKey(a) < pairKey(b) ? -1 : pairKey(a) > pairKey(b) ? 1 : 0) } : {}),
         links: sortedUnique(inputs.links),
     });
 }
@@ -278,7 +309,7 @@ export const AUTH_BASIS_CAP = 64;
 const PROOFS = ['origin-claim', 'claim-mismatch', 'legacy-window', 'unbound', 'cli-identity', 'in-process', 'none'];
 const RULES = Object.keys(VIA_OF);
 /** Rules that admit on shared teams: their basis lists at least one, each once. Every other rule has an empty basis. */
-const SHARED_RULES = ['roster-shared', 'canvas-shared', 'remote-ref-samezone', 'remote-ref-foreign', 'peer-org'];
+const SHARED_RULES = ['roster-shared', 'canvas-shared', 'remote-ref-samezone', 'remote-ref-foreign', 'remote-ref-cli', 'peer-org'];
 /** A record born more than this far in the future is a forgery or a broken clock, not a birth. */
 export const AUTH_CLOCK_SKEW_MS = 24 * 60 * 60 * 1000;
 /** Does a verified claim's signed zone cover the judged caller (the same name, or `<zone>/…`)? */
@@ -292,6 +323,7 @@ export function buildAuthorization(admission, facts) {
         ...(facts.claim !== undefined ? { claim: Object.freeze({ caller: facts.claim.caller, origin: facts.claim.origin }) } : {}),
         ingress: facts.ingress,
         via: admission.via,
+        ...(facts.carrierUrl !== undefined ? { carrier_url: facts.carrierUrl } : {}),
         admission_rule: admission.rule,
         basis: Object.freeze([...admission.basis]),
         allowlist_version: facts.allowlistVersion,
@@ -317,6 +349,7 @@ export function canonicalAuthorization(auth) {
         ...(auth.claim !== undefined ? { claim: { caller: auth.claim.caller, origin: auth.claim.origin } } : {}),
         ingress: auth.ingress,
         via: auth.via,
+        ...(auth.carrier_url !== undefined ? { carrier_url: auth.carrier_url } : {}),
         admission_rule: auth.admission_rule,
         basis: sortedUnique(auth.basis),
         allowlist_version: auth.allowlist_version,
@@ -335,6 +368,17 @@ export function authorizationRef(auth) {
     return createHash('sha256').update(canonicalAuthorization(auth)).digest('hex').slice(0, 16);
 }
 const boundedString = (v, allowEmpty = false) => typeof v === 'string' && (allowEmpty || v !== '') && v.length <= AUTH_STRING_CAP;
+const validCarrierUrl = (v) => {
+    if (!boundedString(v))
+        return false;
+    try {
+        const url = new URL(v);
+        return (url.protocol === 'http:' || url.protocol === 'https:') && url.origin === v;
+    }
+    catch {
+        return false;
+    }
+};
 /**
  * Restore-side allowlist for one persisted record (design §2.5): all of it or
  * none of it — a record with any field outside its closed set or bounds, or
@@ -362,6 +406,8 @@ export function parseAuthorization(raw, now = Date.now()) {
     const rule = r.admission_rule;
     if (r.via !== VIA_OF[rule])
         return undefined;
+    if (rule === 'remote-ref-cli' ? !validCarrierUrl(r.carrier_url) : r.carrier_url !== undefined)
+        return undefined;
     if (!Array.isArray(r.basis) || r.basis.length > AUTH_BASIS_CAP || !r.basis.every(b => boundedString(b)))
         return undefined;
     if (new Set(r.basis).size !== r.basis.length)
@@ -390,10 +436,13 @@ export function parseAuthorization(raw, now = Date.now()) {
     const claimProof = ['origin-claim', 'claim-mismatch', 'unbound', 'cli-identity'].includes(r.proof);
     if ((claim !== undefined) !== claimProof)
         return undefined;
-    if (claim !== undefined && r.proof === 'origin-claim' && !claimCovers(r.caller, claim.caller))
+    if (claim !== undefined && r.proof === 'origin-claim' && (rule === 'remote-ref-cli' ? claim.origin !== r.carrier_url : !claimCovers(r.caller, claim.caller)))
+        return undefined;
+    if (rule === 'remote-ref-cli' && (r.proof !== 'origin-claim' || claim === undefined))
         return undefined;
     return buildAuthorization({ ok: true, via: VIA_OF[rule], rule, basis: r.basis }, {
         caller: r.caller, proof: r.proof, ...(claim !== undefined ? { claim } : {}),
+        ...(rule === 'remote-ref-cli' ? { carrierUrl: r.carrier_url } : {}),
         ingress: r.ingress, allowlistVersion: r.allowlist_version, target: r.target,
         receiptTarget: r.receipt_target, receivedAt: r.received_at, targetBusy: r.target_busy === true,
     });

package/lib/task-ledger.js

@@ -65,7 +65,7 @@ export const TASK_STALE_TTL_MS = 24 * 60 * 60_000;
 const ARCHIVE_ENDS = ['receipt', 'echo', 'abandoned', 'cancelled', 'evicted'];
 /** Summary marker {@link TaskLedger.resolveEcho} writes on echo-settled rows. */
 const ECHO_SUMMARY = '(settled by content echo)';
-const SENDER_KINDS = ['session', 'host', 'bridge'];
+const SENDER_KINDS = ['session', 'host', 'bridge', 'cli'];
 /** Longest sender id kept; anything longer is malformed, not truncated. */
 export const SENDER_ID_CAP = 256;
 /**
@@ -120,6 +120,7 @@ function withAuth(raw, entry, now) {
 /** #139: the routing facts settlement reads, copied between a row and its archive entry. */
 function routingOf(row) {
     return {
+        ...(row.forwarded === true ? { forwarded: true } : {}),
         ...(row.peerKey !== undefined ? { peerKey: row.peerKey } : {}),
         ...(row.peerHost !== undefined ? { peerHost: row.peerHost } : {}),
         ...(row.deliveredTo !== undefined ? { deliveredTo: row.deliveredTo } : {}),
@@ -133,6 +134,7 @@ function birthFacts(peer, birth) {
     const remote = peer !== 'local' && !peer.startsWith('local:');
     return {
         ...(!remote && birth.auth !== undefined && birth.auth.ingress === 'local' ? { auth: birth.auth } : {}),
+        ...(remote && birth.forwarded === true ? { forwarded: true } : {}),
         ...(remote && fact(birth.peerKey) ? { peerKey: birth.peerKey } : {}),
         ...(remote && fact(birth.peerHost) ? { peerHost: birth.peerHost } : {}),
         ...(fact(birth.deliveredTo) ? { deliveredTo: birth.deliveredTo } : {}),
@@ -150,6 +152,7 @@ function withRouting(entry) {
     const fact = (v) => typeof v === 'string' && v !== '' && v.length <= ROUTING_FACT_CAP;
     const remoteOutbound = entry.direction === 'outbound' && typeof entry.peer === 'string' && entry.peer !== 'local' && !entry.peer.startsWith('local:');
     return {
+        ...(remoteOutbound && entry.forwarded === true ? { forwarded: true } : {}),
         ...(remoteOutbound && fact(entry.peerKey) ? { peerKey: entry.peerKey } : {}),
         ...(remoteOutbound && fact(entry.peerHost) ? { peerHost: entry.peerHost } : {}),
         ...(fact(entry.deliveredTo) ? { deliveredTo: entry.deliveredTo } : {}),