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

package/lib/index.js

@@ -28,12 +28,15 @@ export function resolveCallerLabel(input) {
 }
 import { signCard, verifyCard } from "./card.js";
 import { GroupStore } from "./group-store.js";
-import { CanvasStore, isRemoteMemberRef } from "./canvas-store.js";
+import { CanvasStore, canvasNameReserved, isRemoteMemberRef } from "./canvas-store.js";
 import { decodeSessionLog, extractTranscript, TRANSCRIPT_MAX_FILE_BYTES } from "./session-transcript.js";
 import { LayoutStore } from "./layout-store.js";
 import { 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({
@@ -2043,7 +2052,10 @@ export function apply(ctx, config) {
             // without a log.
             void runReceiptLadder({
                 deliver: async (team) => {
-                    const delivered = await dispatchAnywhere(team, receipt, session, undefined, new AbortController().signal, true);
+                    // gh#217: across hosts the caller admits a session face it linked, never this host's process label; a
+                    // task for the bare process team keeps the label, the only host face the settlement judge accepts (N1).
+                    const peerCaller = row?.auth?.target.includes('/') === true ? sessionTeamOf(target) : undefined;
+                    const delivered = await dispatchAnywhere(team, receipt, session, undefined, new AbortController().signal, true, undefined, peerCaller);
                     // gh#141: the caller lane pays this delivery's inbound row across hosts (a
                     // same-host receipt already settled it in-process), unless the caller
                     // refused it. The owner tier is no payment here — but an owner mailbox
@@ -2136,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
@@ -2379,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) {
@@ -2390,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));
@@ -2415,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;
             }
@@ -2440,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;
@@ -2531,10 +2545,13 @@ export function apply(ctx, config) {
             config,
             cliDeposits,
             canvasStore,
+            canvasNameReserved: name => canvasNameReserved(name, config.team, ownerAllowlist, teamMemberships),
             sessionNodes,
             joinedSessions,
             idempotencyStore,
             verifyOriginClaim,
+            remoteCliProof,
+            forwardDirect: request => forwardDirect(request),
             callerLinkedToThisHost, get ownCardUrl() { return ownCardUrl; },
             recordActivity,
             bumpLegacyInbound: () => { legacyInboundCount += 1; },
@@ -2547,6 +2564,7 @@ export function apply(ctx, config) {
             readSessionLogTail,
             taskLedger,
             refuseIfFlooded,
+            refuseIfQueueFull,
             settleAndAnnounce,
             touchWakeDemand: () => { lastWakeDemandAt = Date.now(); },
             session,
@@ -2872,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();
@@ -3213,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
@@ -3248,61 +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();
-                // 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 && !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) && !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({
@@ -3465,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
@@ -3734,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
@@ -3772,7 +3811,18 @@ export function apply(ctx, config) {
      * receipt ladder can distinguish "delivered" from "no route" and its
      * owner escalation actually fires for cross-node callback addresses.
      */
-    async function dispatchAnywhere(team, message, callerSession, contextId, signal, asyncMode, taskId) {
+    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)
@@ -3789,7 +3839,7 @@ export function apply(ctx, config) {
         }
         let lastError = 'no candidate delivered';
         for (const candidate of candidates) {
-            const result = await dispatchPeerCandidate(candidate, team, message, contextId, signal, callerSession, asyncMode, taskId);
+            const result = await dispatchPeerCandidate(candidate, team, message, contextId, signal, peerCaller ?? callerSession, asyncMode, taskId);
             if (result.ok)
                 return result;
             lastError = result.error;
@@ -3839,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/layout-store.js

@@ -20,6 +20,8 @@ export const SCALE_MAX = 3;
 /** Document shape caps: a layout taxonomy, not a database. */
 export const LAYOUT_NODE_CAP = 256;
 export const LAYOUT_FRAME_CAP = 96;
+/** Canvas names stay ≤40; roster keys carry an extra seven-character namespace. */
+const validFrame = (name) => name !== '' && !name.includes('/') && (name.startsWith('roster:') ? name.length > 7 && name.length <= 47 : name.length <= 40);
 function clampCoord(v) {
     const n = typeof v === 'number' ? v : Number.NaN;
     if (!Number.isFinite(n))
@@ -79,8 +81,7 @@ function clampDoc(raw) {
     const frames = {};
     if (rec.frames !== null && typeof rec.frames === 'object') {
         for (const [name, rect] of Object.entries(rec.frames)) {
-            // Frame keys mirror canvas team names: same discipline (no '/', cap 40).
-            if (typeof name !== 'string' || name === '' || name.includes('/') || name.length > 40)
+            if (!validFrame(name))
                 continue;
             const r = clampRect(rect);
             if (r !== undefined)

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/roster-op.js

@@ -0,0 +1,104 @@
+/** Owner-controlled roster mutations from the planning board. */
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { applyOwnerSettings } from "./owner-settings.js";
+import { TEAM_NAME_MAX } from "./team-store.js";
+/** Writes complete snapshots; on a failed second write, rolls the first back. */
+export function rosterOp(d, raw) {
+    const b = raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+    const op = b.op;
+    const name = b.name;
+    const team = typeof name === 'string' ? d.zone + '/' + name : '';
+    const action = op === 'remove-member' || op === 'dissolve' ? 'leave' : 'join';
+    const actor = 'human:owner';
+    const audit = (id, ok, why) => d.audit(action, team, id, ok, why);
+    const reject = (error) => { audit(typeof b.id === 'string' ? b.id : actor, false, error); return { ok: false, error }; };
+    if (typeof name !== 'string' || name !== name.trim() || name.length < 1 || name.length > 40 || name.includes('/') || name.includes('*') || name.startsWith('roster:') || /^\d+$/.test(name) || /[\r\n]/.test(name) || team.length > TEAM_NAME_MAX)
+        return reject('name must be one exact local roster name (no slash or canvas path)');
+    if (op === 'create' && d.canvasExists(name))
+        return reject('a canvas team already uses this name');
+    if (op !== 'create' && op !== 'add-member' && op !== 'remove-member' && op !== 'dissolve')
+        return reject('invalid roster operation');
+    const current = d.store.membersOf(team);
+    const allow = [...d.allowlist()];
+    const allowed = allow.includes(team);
+    if (op === 'add-member' && !allowed)
+        return reject('roster name is no longer in the exact allowlist');
+    if (op !== 'create' && !allowed && current.length === 0)
+        return reject('no such roster team');
+    if (op === 'create' && (!Array.isArray(b.ids) || b.ids.length < 2 || b.ids.some(x => typeof x !== 'string')))
+        return reject('create needs at least two joined local session ids');
+    if ((op === 'add-member' || op === 'remove-member') && (typeof b.id !== 'string' || b.id === ''))
+        return reject('local session id is required');
+    const add = op === 'create' ? b.ids : op === 'add-member' ? [b.id] : [];
+    if (new Set(add).size !== add.length || add.some(id => id === '' || !d.joined(id)))
+        return reject('only distinct joined local sessions can join a roster');
+    const members = op === 'create' || op === 'add-member' ? [...new Set([...current, ...add])] : op === 'remove-member' ? current.filter(id => id !== b.id) : [];
+    const nextAllow = op === 'create' && !allowed ? [...allow, team] : op === 'dissolve' ? allow.filter(x => x !== team) : allow;
+    const patch = join(d.home, 'cordis.patch.yml');
+    let before;
+    if ((op === 'create' && !allowed) || (op === 'dissolve' && allowed)) {
+        try {
+            before = existsSync(patch) ? readFileSync(patch, 'utf8') : undefined;
+        }
+        catch (error) {
+            return reject('owner patch unavailable: ' + String(error));
+        }
+    }
+    const savePatch = (content) => {
+        mkdirSync(dirname(patch), { recursive: true });
+        const tmp = patch + '.' + String(process.pid) + '.tmp';
+        try {
+            writeFileSync(tmp, content, { mode: 0o600 });
+            renameSync(tmp, patch);
+        }
+        catch (error) {
+            try {
+                unlinkSync(tmp);
+            }
+            catch { /* original remains */ }
+            ;
+            throw error;
+        }
+    };
+    let patchWritten = false;
+    try {
+        if (op === 'create' && !allowed) {
+            savePatch(applyOwnerSettings(before ?? '', { teamJoinAllowlist: nextAllow }).yaml);
+            patchWritten = true;
+        }
+        const done = d.store.replaceTeam(team, members);
+        if (!done.ok)
+            throw new Error(done.error);
+        if (op === 'dissolve' && allowed)
+            savePatch(applyOwnerSettings(before ?? '', { teamJoinAllowlist: nextAllow }).yaml);
+        d.setAllowlist(nextAllow);
+    }
+    catch (error) {
+        try {
+            if (patchWritten) {
+                if (before === undefined) {
+                    if (existsSync(patch))
+                        unlinkSync(patch);
+                }
+                else
+                    savePatch(before);
+            }
+            if (op === 'dissolve') {
+                const undone = d.store.replaceTeam(team, current);
+                if (!undone.ok)
+                    throw new Error(undone.error);
+            }
+        }
+        catch (rollback) {
+            return reject(String(error) + '; rollback failed: ' + String(rollback));
+        }
+        return reject(String(error));
+    }
+    const delta = op === 'dissolve' ? current : op === 'remove-member' ? current.filter(id => !members.includes(id)) : members.filter(id => !current.includes(id));
+    if ((op === 'create' && !allowed) || (op === 'dissolve' && allowed))
+        audit(actor, true, op === 'create' ? 'created roster name' : 'dissolved roster name');
+    for (const id of delta)
+        audit(id, true, 'by human:owner');
+    return { ok: true, team, members };
+}

package/lib/skill/references/cli.md

@@ -5,7 +5,7 @@ agent harness — joins the network through the `a2a-net` command (bin of
 `@nelsonlongxiang/dsh-open-a2a-net`, 0.6.27+). It has its own key, deposits
 itself on ONE home host, and receives through a mailbox; nothing wakes.
 `a2a-net help` prints the command map, `a2a-net tools` the alignment with the
-ten model tools.
+model tools.
 
 ## Identity and home host
 
@@ -111,10 +111,11 @@ ten 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/skill/references/router.md

@@ -87,7 +87,7 @@
 ### 已知陷阱
 - held 状态超过 72 小时就判为不通过：观察期里要及时 release 或撤回。
 - a2a CLI 户口 4 小时过期，发送前先执行 `publish`。
-- `verify-probe.mjs` 会清空固定的 TEMP 目录 `dsh-a2a-submission`，跑之前确认里面没有别人的东西。
+- `verify-probe.mjs` 每轮把提交树导出到一个新建的唯一目录 `<TEMP>/dsh-a2a-submission-XXXXXX`，并把路径写进 `verify/probe-summary.json`；`verify-recursive.mjs` 只认这个路径，不再读、也不再清空旧的固定目录 `dsh-a2a-submission`（#213）。这些导出目录不会自动删除，需要时手动清理自己的。
 
 ### 当前重点
 - 跑通第一条真实的人类事件。需要三件事：