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

package/lib/direct-forward.js

@@ -2,10 +2,29 @@
 import { DEFAULT_HOP_BUDGET, guardHeader, mintGuard } from "./recursion-guard.js";
 import { briefOf } from "./task-ledger.js";
 import { parseReceipt } from "./receipt.js";
+import { splitCanvasOwner } from "./canvas-id.js";
+import { claimCovers } from "./task-auth.js";
+/** An early receipt waits at most this long for its forward row to be born (#298). */
+export const BIRTH_WAIT_CAP_MS = 60_000;
 /** Birth barrier exists only for eligible, actively dispatched tasks; receipts never reserve a slot. */
 export class ForwardBirths {
+    waitCapMs;
     pending = new Map();
-    wait(taskId) { return this.pending.get(taskId); }
+    constructor(waitCapMs = BIRTH_WAIT_CAP_MS) {
+        this.waitCapMs = waitCapMs;
+    }
+    /**
+     * Resolves when the birth is released or after the cap, whichever is first. After the cap the receipt
+     * is judged by the normal rules against whatever row exists then — never accepted in advance (#298).
+     */
+    wait(taskId) {
+        const birth = this.pending.get(taskId);
+        if (birth === undefined)
+            return undefined;
+        let timer;
+        const cap = new Promise(resolve => { timer = setTimeout(resolve, this.waitCapMs); timer.unref?.(); });
+        return Promise.race([birth, cap]).finally(() => clearTimeout(timer));
+    }
     begin(taskId) {
         if (this.pending.size >= 64 || this.pending.has(taskId))
             return undefined;
@@ -16,29 +35,33 @@ export class ForwardBirths {
 }
 export function createDirectForward(d) {
     return async (request) => {
-        const refuse = (why) => ({ ok: false, code: -32000, task_id: request.taskId, error: 'not forwarded: ' + why });
+        const refuse = (why, next) => ({ ok: false, code: -32000, task_id: request.taskId, error: 'not forwarded: ' + why, ...(next !== undefined ? { next } : {}) });
+        const publish = 'run `a2a-net publish` to renew this CLI deposit on its home host, then send again with a new task id';
         if (!d.enabled())
-            return refuse('forwardDirect is off');
+            return refuse('forwardDirect is off', 'ask this host\'s operator to set forwardDirect: true (the default since 0.6.38)');
         if (d.isolated())
-            return refuse('host is isolated');
+            return refuse('host is isolated', 'this host forwards nothing while isolated; deposit the CLI on another home host');
         if (request.guarded)
             return refuse('an inbound X-A2A-Guard is present; already forwarded');
         if (!request.localCliProof || !d.deposited(request.caller))
-            return refuse('caller is not a proven online local CLI deposit');
-        const scope = await d.scope(request.caller, request.team);
+            return refuse('caller is not a proven online local CLI deposit', publish);
+        // #282 S2: candidates honour an owner-qualified id; scope, the peer, the receivers and the ledger see the plain team.
+        const plainTeam = splitCanvasOwner(request.team).team;
+        const scope = await d.scope(request.caller, plainTeam);
         if (!scope.ok)
-            return refuse('target is outside sender scope: ' + scope.error);
+            return refuse('target is outside sender scope: ' + scope.error, `ask this host's operator to link ${request.team} here: drag it (or one of its members) into a canvas team on this host`);
         const failures = [];
         const directory = await d.candidates(request.team, failures, request.caller);
         const guard = guardHeader({ ...mintGuard(), hopBudget: DEFAULT_HOP_BUDGET - 1 });
         for (const url of directory.urls) {
             if (!d.deposited(request.caller))
-                return refuse('local CLI deposit expired before dispatch');
+                return refuse('local CLI deposit expired before dispatch', publish);
             const peerCard = await directory.card(url);
-            const receivers = request.team.includes('/canvas/') ? peerCard?.canvasOrg?.find(row => row.team === request.team)?.members.filter(member => member !== request.caller) : undefined;
-            if (request.team.includes('/canvas/')) {
-                if (receivers === undefined || receivers.length === 0 || receivers.some(member => !d.memberLinked(member))) {
-                    failures.push(url + ': forwarding a canvas requires a direct operator link to every receiving member for its receipt return path');
+            const receivers = plainTeam.includes('/canvas/') ? peerCard?.canvasOrg?.find(row => row.team === plainTeam)?.members.filter(member => member !== request.caller) : undefined;
+            if (plainTeam.includes('/canvas/')) {
+                // #282 S3 (same team authorizes): the owner's signed canvas is the return path; receipts settle only from these frozen receivers on this peer key (#274).
+                if (receivers === undefined || receivers.length === 0) {
+                    failures.push(url + ': the owner card lists no receiving member of this canvas');
                     continue;
                 }
             }
@@ -46,12 +69,12 @@ export function createDirectForward(d) {
             const receipt = parseReceipt(request.message) !== null;
             const release = receipt ? () => { } : d.births.begin(request.taskId);
             if (release === undefined)
-                return refuse('forward receipt correlation capacity is full');
+                return refuse('forward receipt correlation capacity is full', 'wait for in-flight forwards to settle, then send again with a new task id');
             try {
                 // The same selected-peer snapshot supplies both return-link gate and settlement birth.
-                const answer = await d.dispatch(url, request, guard);
+                const answer = await d.dispatch(url, plainTeam === request.team ? request : { ...request, team: plainTeam }, guard);
                 const result = !answer.ok && answer.ownBudgetExhausted === true ? { ...answer, code: -32005 } : answer;
-                d.activity(request.team, url, result.ok);
+                d.activity(plainTeam, url, result.ok);
                 if (result.ok || result.code === -32005) {
                     // A receipt owes no receipt; native bridge rounds have no A2A receipt contract.
                     // Match routeTrunk/trackOwedTask rather than manufacturing an unpayable debt.
@@ -63,9 +86,9 @@ export function createDirectForward(d) {
                     const birth = { forwarded: true, ...(request.auth !== undefined ? { auth: request.auth } : {}), ...(peerCard?.publicKey ? { peerKey: peerCard.publicKey } : {}), ...(peerCard?.session ? { peerHost: peerCard.session } : {}), ...(deliveredTo !== undefined ? { deliveredTo } : {}), ...(receivers !== undefined ? { receiverMembers: receivers } : {}) };
                     // Exactly one outbound row. A completed sync response is receiptless bookkeeping.
                     if (result.ok && (result.task_status === 'TASK_STATE_COMPLETED' || result.receipt === 'none'))
-                        d.ledger.trackReceiptless(request.taskId, request.team, url, request.contextId, briefOf(request.message), { kind: 'cli', id: request.caller }, birth);
+                        d.ledger.trackReceiptless(request.taskId, plainTeam, url, request.contextId, briefOf(request.message), { kind: 'cli', id: request.caller }, birth);
                     else
-                        d.ledger.track(request.taskId, request.team, url, request.contextId, briefOf(request.message), { kind: 'cli', id: request.caller }, birth);
+                        d.ledger.track(request.taskId, plainTeam, url, request.contextId, briefOf(request.message), { kind: 'cli', id: request.caller }, birth);
                     return result;
                 }
                 // The shared dispatcher's sync recovery query may prove a definitive failed
@@ -78,6 +101,29 @@ export function createDirectForward(d) {
                 release();
             }
         }
-        return { ok: false, code: -32004, task_id: request.taskId, error: 'forwarding to "' + request.team + '" failed: ' + (failures.join('; ') || 'no eligible peer candidate') };
+        const noReceiver = failures.some(f => f.includes('lists no receiving member'));
+        const next = noReceiver ? `the owner's canvas ${plainTeam} lists no member besides you; ask its owner to add one, or route to a member's own handle` : failures.length === 0 ? `no linked peer lists ${request.team}; check the name with \`a2a-net teams\`` : undefined;
+        return { ok: false, code: -32004, task_id: request.taskId, error: 'forwarding to "' + request.team + '" failed: ' + (failures.join('; ') || 'no eligible peer candidate'), ...(next !== undefined ? { next } : {}) };
     };
 }
+/**
+ * #282 S3 (same team authorizes): the admission basis for a receipt delivered to a local CLI mailbox
+ * from a member the home never linked — only for that CLI's own pending forward, only from a receiver
+ * frozen at birth, only when the body-bound (Sig3) claim's card key is the frozen peer key. Anything else:
+ * undefined. Trust assumption (design D2): the selected owner host is honest about its own canvas — it may
+ * list any label as a receiver, including one of this host's session labels in the same zone.
+ */
+export function forwardReceiptBasis(row, caller, cliHandle, claim) {
+    // The signer's zone must cover the caller label: B never signs for another zone's member (review of #287 M4).
+    if (!claimCovers(caller, claim.caller))
+        return undefined;
+    if (row === undefined || row.status !== 'pending' || row.forwarded !== true || row.sender?.kind !== 'cli' || row.sender.id !== cliHandle)
+        return undefined;
+    // Body-bound (Sig3) only: a stripped Sig3 would let a captured envelope carry another body (review of #287 P3-1).
+    if (!claim.bound || claim.bodyBound !== true || row.peerKey === undefined || claim.card.publicKey !== row.peerKey)
+        return undefined;
+    // A legacy row's deliveredTo may be the canvas handle itself (#272/#275): never a receiver.
+    if (row.deliveredTo !== undefined && (row.deliveredTo === row.team || row.deliveredTo.includes('/canvas/')))
+        return undefined;
+    return (row.deliveredTo !== undefined ? [row.deliveredTo] : row.receiverMembers ?? []).includes(caller) ? `peer-org:${row.team}` : undefined;
+}

package/lib/faces/admin.js

@@ -19,6 +19,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { canvasNameReserved as reservedCanvasName, isRemoteMemberRef, validRemoteMemberRef } from "../canvas-store.js";
+import { qualifiedCanvasId } from "../canvas-id.js";
 import { refreshPeerCard, registerCanvasNotify } from "./canvas-notify.js";
 import { CLI_HANDLE_RE } from "../cli-deposit.js";
 import { applyOwnerSettings, parseSeatNames } from "../owner-settings.js";
@@ -135,6 +136,8 @@ export function registerAdminFaces(webServer, d) {
                         teams: canvasStore.list().map(name => ({
                             name,
                             team: canvasTeamOf(name),
+                            // #282 S2: the owner-qualified routing id.
+                            id: `${canvasTeamOf(name)}@${d.ownCanvasFingerprint}`,
                             // gh#152: members as the local tiers read them (gh#131). One
                             // of this host's own handles renders as the local session it
                             // names — join/live facts instead of an opaque remote chip — and
@@ -321,7 +324,7 @@ export function registerAdminFaces(webServer, d) {
                         const unreachable = card !== undefined && entry?.missAt !== undefined ? { unreachable: true } : {};
                         return Array.isArray(org)
                             ? { url, ...unreachable, org: org.filter((e) => e !== null && typeof e === 'object')
-                                    .map(e => ({ name: typeof e.name === 'string' ? e.name : '', team: typeof e.team === 'string' ? e.team : '', members: Array.isArray(e.members) ? e.members.filter((m) => typeof m === 'string') : [] }))
+                                    .map(e => ({ name: typeof e.name === 'string' ? e.name : '', team: typeof e.team === 'string' ? e.team : '', id: typeof e.team === 'string' ? qualifiedCanvasId(e.team, card?.publicKey) : '', members: Array.isArray(e.members) ? e.members.filter((m) => typeof m === 'string') : [] }))
                                     .filter(e => e.team !== '') }
                             : { url, ...unreachable, org: [] };
                     }),

package/lib/faces/wire.js

@@ -1,11 +1,12 @@
 import { isRemoteMemberRef, validRemoteMemberRef } from "../canvas-store.js";
+import { splitCanvasOwner } from "../canvas-id.js";
 import { CLI_HANDLE_RE } from "../cli-deposit.js";
 import { TRANSCRIPT_DEFAULT_LIMIT, TRANSCRIPT_MAX_LIMIT } from "../session-transcript.js";
 import { refuseIfBudgetExhausted } from "../recursion-guard.js";
 import { peerPayloadFingerprint, WIRE_ERROR_IDEMPOTENCY_CONFLICT, WIRE_ERROR_REPLAY_REJECTED } from "../idempotency-store.js";
 import { briefOf } from "../task-ledger.js";
 import { parseReceipt, taskIdRefusal } from "../receipt.js";
-import { buildAuthorization, claimCovers, refusalOf } from "../task-auth.js";
+import { buildAuthorization, claimCovers, nextOf, refusalOf } from "../task-auth.js";
 import { isRootOriginUrl } from "../origin-claim.js";
 import { withResponseFields } from "../response-fields.js";
 import { WIRE_ERROR_PAYLOAD_TOO_LARGE, withinRouteBodyCap } from "../transport-caps.js";
@@ -434,7 +435,9 @@ export function registerWireFaces(webServer, d) {
                         return;
                     }
                 }
-                const team = typeof body.team === 'string' ? body.team : '';
+                // #282 S2: our own `<canvas>@<fp8>` is our canvas; a foreign suffix stays for the forward walk.
+                const ownerQualified = splitCanvasOwner(typeof body.team === 'string' ? body.team : '');
+                const team = ownerQualified.owner !== undefined && ownerQualified.owner === d.ownCanvasFingerprint ? ownerQualified.team : typeof body.team === 'string' ? body.team : '';
                 const message = typeof body.message === 'string' ? body.message : '';
                 const caller = typeof body.caller_session === 'string' ? body.caller_session : '';
                 // P2 receipt-callback: where THIS node's receipt should route on
@@ -482,11 +485,25 @@ export function registerWireFaces(webServer, d) {
                 const foreignCli = config.teamScopeRouting && CLI_HANDLE_RE.test(caller) && cliDeposits.get(caller) === undefined;
                 const earlyClaim = foreignCli ? await verifyOriginClaim(req, { cli: true, rawBody }) : undefined;
                 const cliProof = foreignCli && earlyClaim?.ok ? await remoteCliProof(caller, earlyClaim).catch(() => undefined) : undefined;
-                const admission = a2aCallerAdmission(caller, team, cliProof);
+                let admission = a2aCallerAdmission(caller, team, cliProof);
+                // #282 S3 (same team authorizes): a receipt for this host's own forward, to the CLI that sent it, from a
+                // receiver frozen at birth on the selected peer's key — the owner's signed canvas is the return path.
+                const echoed = !admission.ok && cliDeposits.get(team) !== undefined ? parseReceipt(message) : null;
+                if (echoed !== null) {
+                    // Verify first, so an unsigned or Sig2-only caller cannot hold the connection on an in-flight forward (#287 review P3);
+                    // then a body-bound receipt may beat the dispatch's HTTP answer: wait for this forward's row to be born (#287 P2).
+                    const receiptClaim = earlyClaim ?? await verifyOriginClaim(req, { cli: true, rawBody });
+                    if (receiptClaim.ok && receiptClaim.bodyBound === true)
+                        await waitForForwardBirth(message);
+                    const basis = receiptClaim.ok ? d.forwardReceiptBasis(echoed.taskId, caller, team, receiptClaim) : undefined;
+                    if (basis !== undefined)
+                        admission = { ok: true, via: 'peer-org', rule: 'peer-org', basis: [basis] };
+                }
                 const callerRefusal = refusalOf(admission);
                 if (callerRefusal !== undefined || !admission.ok) {
                     recordActivity('in', team, caller === '' ? 'anonymous' : caller, false);
-                    const payload = JSON.stringify({ error: callerRefusal, code: -32000, team, task_status: 'TASK_STATE_FAILED' });
+                    const next = nextOf(admission);
+                    const payload = JSON.stringify({ error: callerRefusal, code: -32000, team, task_status: 'TASK_STATE_FAILED', ...(next !== undefined ? { next } : {}) });
                     res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
                     res.end(payload);
                     return;
@@ -589,7 +606,8 @@ export function registerWireFaces(webServer, d) {
                 // quiet window around it.
                 d.touchWakeDemand();
                 const forwardMiss = async (original) => {
-                    const result = await d.forwardDirect({ team, message, caller, taskId, contextId, noWait,
+                    // #282 S2 review P1: forward with the id the caller sent — our own `@fp8` must find no other owner.
+                    const result = await d.forwardDirect({ team: typeof body.team === 'string' && ownerQualified.owner !== undefined ? body.team : team, message, caller, taskId, contextId, noWait,
                         auth: buildAuthorization(admission, { caller, proof: callerProof, ...(claim.ok ? { claim: { caller: claim.caller, origin: originOf(claim.callerUrl) } } : {}), ingress: 'wire', allowlistVersion: admittedAt.version, target: team, receiptTarget: caller, receivedAt: admittedAt.at }),
                         localCliProof: claim.ok && claim.cli === true && claim.bound && claim.caller === caller, guarded: req.headers['x-a2a-guard'] !== undefined }).catch((error) => ({ ok: false, error: `forwarding unavailable: ${String(error)}`, code: -32000, task_id: taskId }));
                     const failure = result.ok ? '' : await d.diagnoseCanvas(team, original + ' — ' + result.error, claim.ok && claim.cli === true && claim.bound && claim.caller === caller ? caller : undefined);
@@ -597,7 +615,7 @@ export function registerWireFaces(webServer, d) {
                         idempotencyStore.recordOutcome(taskId, { status: 'failed', error: failure });
                     else if (result.ok && result.task_status === 'TASK_STATE_COMPLETED')
                         idempotencyStore.recordOutcome(taskId, { status: 'completed', reply: result.reply });
-                    const payload = JSON.stringify(result.ok ? { routed: true, ...(result.task_status === 'TASK_STATE_DELIVERED' ? { delivered: true } : { result: { text: result.reply } }), team, task_id: taskId, context_id: contextId, task_status: result.task_status, consumed: result.consumed, bridge: result.bridge, receipt: result.receipt, forwarded: true } : { error: failure, code: result.code ?? -32000, receipt: result.receipt, task_id: taskId, team, task_status: result.code === -32005 ? 'TASK_STATE_DELIVERED' : 'TASK_STATE_FAILED' });
+                    const payload = JSON.stringify(result.ok ? { routed: true, ...(result.task_status === 'TASK_STATE_DELIVERED' ? { delivered: true } : { result: { text: result.reply } }), team, task_id: taskId, context_id: contextId, task_status: result.task_status, consumed: result.consumed, bridge: result.bridge, receipt: result.receipt, forwarded: true } : { error: failure, code: result.code ?? -32000, receipt: result.receipt, task_id: taskId, team, task_status: result.code === -32005 ? 'TASK_STATE_DELIVERED' : 'TASK_STATE_FAILED', ...(result.next !== undefined ? { next: result.next } : {}) });
                     res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
                     res.end(payload);
                 };

package/lib/flood-guard.js

@@ -104,7 +104,9 @@ export function createFloodGuard(outcomes, recordActivity) {
         const error = 'flood-guard: ' + reason + ' (gh#91): file data must use an independent channel; no delivery occurred' + (advice === undefined ? '' : '; use-file-channel: ' + advice.message);
         outcomes.recordOutcome(taskId, { status: 'failed', error });
         recordActivity('in', team, caller, false);
-        const payload = JSON.stringify({ error, reason, code: WIRE_ERROR_RATE_LIMITED, task_id: taskId, team, delivered: false, task_status: 'TASK_STATE_FAILED' });
+        // #282 S1: one next step — file bytes go through the file channel, never chat messages.
+        const next = 'send file data with a2a_file_send / `a2a-net file send <path> <team>` instead of message chunks; resend other text as one message with a new task id';
+        const payload = JSON.stringify({ error, reason, code: WIRE_ERROR_RATE_LIMITED, task_id: taskId, team, delivered: false, task_status: 'TASK_STATE_FAILED', next });
         res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
         res.end(payload);
         return true;

package/lib/index.js

@@ -5,7 +5,7 @@
  * inbound direct routes into live agent sessions.
  * @module @nelsonlongxiang/dsh-open-a2a-net
  */
-import { createHash, createPrivateKey, generateKeyPairSync, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, timingSafeEqual } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { networkInterfaces } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -26,7 +26,7 @@ export function resolveCallerLabel(input) {
         return input.nodeTeam;
     return input.sessionLabel;
 }
-import { signCard, verifyCard } from "./card.js";
+import { encodePublicKey, signCard, verifyCard } from "./card.js";
 import { GroupStore } from "./group-store.js";
 import { CanvasStore, canvasNameReserved, isRemoteMemberRef } from "./canvas-store.js";
 import { decodeSessionLog, extractTranscript, TRANSCRIPT_MAX_FILE_BYTES } from "./session-transcript.js";
@@ -43,20 +43,20 @@ import { createDirectForward, ForwardBirths } from "./direct-forward.js";
 import { TeamMembershipStore } from "./team-store.js";
 import { PeerStore } from "./peer-store.js";
 import { SelfReferralFilter } from "./self-suppress.js";
-import { TaskLedger, TASK_STALE_TTL_MS, SUMMARY_CAP, briefOf } from "./task-ledger.js";
+import { TaskLedger, SUMMARY_CAP, briefOf } from "./task-ledger.js";
 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 { createQueueGuard, queueFullRefusal, QUEUE_FULL_NEXT, WIRE_ERROR_QUEUE_FULL } from "./queue-guard.js";
 import { resolveZone } from "./zone.js";
 import { registerA2aNetworkSkill } from "./skill-registration.js";
 import { isRootOriginUrl, sameMountedUrl, signOriginClaim, verifyOriginClaim as verifyOriginClaimOf } from "./origin-claim.js";
 import { AuthObserver } from "./auth-observer.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';
+import { liveRootAgents } from "./live-roots.js";
 import { A2aClient } from "./a2a-client.js";
 import { WIRE_ERROR_PAYLOAD_TOO_LARGE } from "./transport-caps.js";
 import { registerAdminFaces } from "./faces/admin.js";
@@ -80,127 +80,10 @@ export { A2aClient } from "./a2a-client.js";
 export { NATIVE_TEAMS_A2A_FACE_KEY } from "./teams-bridge.js";
 export const name = 'a2a';
 export const inject = ['tools', 'timer', 'systemPrompt'];
-/** Schemastery configuration for the A2A client plugin row. */
-export const Config = s.object({
-    apiKey: s.string().default(''),
-    session: s.string().default(''),
-    team: s.string().default('dsh'),
-    /** S4 fix ③: host-side (agent-less) routing calls — audit them (default) or refuse outright. */
-    gateAgentLessCalls: s.union(['audit', 'refuse']).default('audit'),
-    settlementAuth: s.union(['off', 'observe', 'enforce']).default('observe'),
-    announce: s.boolean().default(false),
-    isolated: s.boolean().default(false),
-    forwardDirect: s.boolean().default(true),
-    agentName: s.string().default('DeepSeek Harness A2A node'),
-    peers: s.array(s.string()).default([]),
-    delegates: s.array(s.object({ name: s.string(), url: s.string(), publicKey: s.string().default('') })).default([]),
-    dshHome: s.string().default(''),
-    sessionNodes: s.boolean().default(true),
-    wakeJoinedOnBoot: s.boolean().default(false),
-    wakePrewarmDelayMs: s.number().default(10_000),
-    wakePrewarmQuietMs: s.number().default(5_000),
-    wakeBootStaggerMs: s.number().default(3_000),
-    wakeReconcile: s.boolean().default(true),
-    wakeReconcileIntervalMs: s.number().default(60_000),
-    wakeReconcileBackoffBaseMs: s.number().default(5_000),
-    wakeReconcileMaxBackoffMs: s.number().default(600_000),
-    /**
-     * S4 (gh#11 N7): the joinable-team curation list. A model calling
-     * a2a_team_join may only declare membership in a team with an EXACT
-     * entry here — trailing-`*` patterns are readable but authorize nothing
-     * (no mint rights: a pattern pre-authorizing every future name under it
-     * would let a model mint teams nobody created). Default empty: the
-     * owner's no-self-join ruling, institutionalized as default-deny; a
-     * refused join carries guidance instead of failing silently.
-     */
-    teamJoinAllowlist: s.array(s.string()).default([]),
-    seatNames: s.dict(s.any()).default({}),
-    /**
-     * S3 (phase-2 default, owner ruling 2026-09-01): route dispatch checks
-     * caller↔target shared team membership before addressing — a session
-     * with no declared team has no network (the unteamed-peer defect the
-     * owner reproduced on 4080 and locally). Fleet compatibility rides the
-     * roster capability flag (0.5.44 cards advertise roster:true; older
-     * peers read as legacy). Set false to restore the open outbound seam.
-     */
-    teamScopeRouting: s.boolean().default(true),
-    /**
-     * S5 (default-on, owner directive 2026-10-20): the information-plane
-     * tools answer from the joined-team scope only — a2a_teams lists
-     * [this host] rows plus peer rows serving a joined team (note field
-     * explains the scope); a2a_status narrows peers / in-flight / activity
-     * to that scope (local traffic and idempotency aggregates stay);
-     * a2a_probe sweeps serving peers and refuses a single URL whose
-     * verified card cannot prove service. A host whose nodes declare no
-     * teams keeps host-internal facts only. Set false to restore
-     * fleet-wide disclosure.
-     */
-    teamScopeInfo: s.boolean().default(true),
-    /**
-     * Peer boundary model — connection layer: an empty list keeps the
-     * historical open-referral posture; a non-empty list admits a referral
-     * only when its host matches an entry (exact host[:port], bare domain
-     * suffix, or full URL). Seeds from `peers` are owner-configured and
-     * unaffected.
-     */
-    peerAllowlist: s.array(s.string()).default([]),
-    /**
-     * Peer boundary model — connection layer: when false, referral URLs are
-     * neither learned nor offered; the tracked set stays the configured seed
-     * set for the lifetime of the config that named them.
-     */
-    referralLearning: s.boolean().default(true),
-    /**
-     * gh#8 (N9): team-name resolution rides the operator-established peer
-     * basis (config seeds + delegates) only; the referral-learned tail's
-     * self-published card claims do not bind team names. Set true to restore
-     * the legacy whole-store basis (fleet migration window).
-     */
-    referralTeamResolution: s.boolean().default(false),
-    /**
-     * #19 D2 (ruling final, owner-level knob): how much of a session team's
-     * activity EXCERPT the card face publishes in sessionTeams descriptions.
-     * 'full' (default) keeps the verbatim tail excerpt; 'masked' truncates
-     * to a shape-only prefix; 'off' omits the description field entirely.
-     * Titles and team handles stay in every tier — the knob is the excerpt,
-     * not the listing.
-     */
-    exposureExcerpt: s.union(['full', 'masked', 'off']).default('full'),
-    /**
-     * gh#9+gh#10 OriginClaim window: absent envelopes still walk N3 during
-     * the window (counted as legacyInbound); closing it rejects them like
-     * failed signatures. See docs/protocol/delivery-origin-auth.md §4.
-     */
-    originClaimWindow: s.boolean().default(true),
-    /**
-     * OriginClaim unbound window: also sign/accept the legacy envelope that
-     * names no audience (counted as unboundInbound); closing it leaves the
-     * audience-bound form only. See docs/protocol/delivery-origin-auth.md §2.1.
-     */
-    originClaimUnboundWindow: s.boolean().default(true),
-    /** Extra OriginClaim audience origins (port-mapped/proxied hosts). */
-    originClaimAudiences: s.array(s.string()).default([]),
-    /** OriginClaim callerUrl override for pocket-tunneled hosts; '' = auto. */
-    originClaimUrl: s.string().default(''),
-    /**
-     * v0.5.23 (async-stall): delay before a delivered-but-unconsumed async
-     * route re-wakes its target with a one-line nudge (defect
-     * 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),
-    remoteRowsTtlMs: s.number().default(15_000),
-    cardTtlMs: s.number().default(172_800_000),
-    flushTimeoutMs: s.number().default(300_000),
-    routeTimeoutMs: s.number().default(1_800_000),
-    taskStaleTtlMs: s.number().default(TASK_STALE_TTL_MS),
-    nativeTeamsInbound: s.boolean().default(false),
-    nativeRoundWaitMs: s.number().default(180_000),
-});
+import { Config } from "./config.js";
+import { canvasOwnerFingerprint, splitCanvasOwner } from "./canvas-id.js";
+import { forwardReceiptBasis } from "./direct-forward.js";
+export { Config };
 /**
  * Register the outbound peer tools, the direct-route endpoint, and (when
  * composed) the announced card and session-node control surface.
@@ -564,6 +447,8 @@ export function apply(ctx, config) {
         ...(delegate.publicKey !== '' ? { publicKey: delegate.publicKey } : {}),
     }));
     const nodePrivateKey = loadOrCreateNodeKey(join(home, 'a2a', 'node-key.pem'));
+    /** #282 S2: this host's canvas owner fingerprint (`<canvas>@<fp8>` names our own canvas). */
+    const ownCanvasFingerprint = canvasOwnerFingerprint(encodePublicKey(createPublicKey(nodePrivateKey)));
     /** Our own card URL once the web server settles — the OriginClaim anchor. */
     let ownCardUrl = '';
     /**
@@ -1360,7 +1245,8 @@ export function apply(ctx, config) {
         // side-effect-only.
         ctx.on('agent/created', ({ agent }) => {
             const agents = ctx.get('agents');
-            if (agents === undefined || !agents.roots().some(root => root.id === agent.id))
+            // #291: hosts without roots() (0.2.2-rc) resolve top-level via list()+delegation depth; never throws.
+            if (agents === undefined || !liveRootAgents(agents).some(root => root.id === agent.id))
                 return undefined;
             liveRoots.set(String(agent.id), agent);
             if (joinedSessions.has(String(agent.id)))
@@ -1375,7 +1261,7 @@ export function apply(ctx, config) {
             // the remount above (leave is the only intent remover).
             sessionNodes.delete(String(agent.id));
         });
-        for (const agent of ctx.get('agents')?.roots() ?? []) {
+        for (const agent of liveRootAgents(ctx.get('agents'))) {
             liveRoots.set(String(agent.id), agent);
             if (joinedSessions.has(String(agent.id)))
                 mountSessionNode(agent);
@@ -1680,7 +1566,7 @@ export function apply(ctx, config) {
                 get unboundInboundCount() { return unboundInboundCount; },
                 get boundMissInboundCount() { return boundMissInboundCount; },
                 get boundMissRecent() { return boundMissRecent; },
-                get ownCardUrl() { return ownCardUrl; },
+                get ownCardUrl() { return ownCardUrl; }, ownCanvasFingerprint,
                 get ownerSeatNames() { return ownerSeatNames; },
                 set ownerSeatNames(v) { ownerSeatNames = v; },
                 get ownerAllowlist() { return ownerAllowlist; },
@@ -1852,7 +1738,7 @@ export function apply(ctx, config) {
             return agents.requireInitiator();
         }
         catch {
-            const roots = agents.roots();
+            const roots = liveRootAgents(agents);
             return roots.length > 0 ? roots[0] : undefined;
         }
     }
@@ -2593,7 +2479,8 @@ export function apply(ctx, config) {
             idempotencyStore,
             verifyOriginClaim,
             remoteCliProof,
-            forwardDirect: request => forwardDirect(request),
+            forwardReceiptBasis: (taskId, caller, cliHandle, claim) => forwardReceiptBasis(taskLedger.find(taskId), caller, cliHandle, claim),
+            forwardDirect: request => forwardDirect(request), ownCanvasFingerprint,
             diagnoseCanvas: (team, reason, caller) => diagnoseCanvas(team, reason, caller),
             callerLinkedToThisHost, get ownCardUrl() { return ownCardUrl; },
             recordActivity,
@@ -3297,6 +3184,7 @@ export function apply(ctx, config) {
             };
         }
         const remote = failures.filter(entry => !entry.startsWith('local: '));
+        const queueFull = failures.some(entry => entry.startsWith('local: target-queue-full'));
         const suffix = team.slice(team.indexOf('/') + 1);
         const near = [...new Set([
                 ...joinedSessions.list().map(id => `${config.team}/${id8(id)}`),
@@ -3313,9 +3201,10 @@ export function apply(ctx, config) {
             `team "${team}" is not published by any configured peer${remote.length > 0 ? ` (unresolved delegations: ${remote.join('; ')})` : ''}`,
             ...failures.filter(entry => entry.startsWith('local: ')).map(entry => `local reason: ${entry.slice('local: '.length)}`),
             near.length > 0 ? `nearby advertised teams: ${near.join(', ')}` : undefined,
-            'next: enumerate live alternatives with a2a_teams; do not retry unchanged; joining is the target session\'s own gesture (its sidebar) — relay that request to the human',
+            // #282 S1: a full local queue means the target exists and is busy — waiting is the only right next step.
+            queueFull ? `next: ${QUEUE_FULL_NEXT}` : 'next: enumerate live alternatives with a2a_teams; do not retry unchanged; joining is the target session\'s own gesture (its sidebar) — relay that request to the human',
         ].filter((line) => line !== undefined);
-        return { ok: false, error: lines.join(' — '), code: -32004 };
+        return queueFull ? { ok: false, error: lines.join(' — '), code: WIRE_ERROR_QUEUE_FULL, next: QUEUE_FULL_NEXT } : { ok: false, error: lines.join(' — '), code: -32004 };
     };
     actTools.registerRoute();
     // #91 file channel F2: a2a_file_send / a2a_file_fetch (src/tools/files.ts).
@@ -3358,9 +3247,9 @@ export function apply(ctx, config) {
             for (const owner of owners.filter(row => row.team === team && !row.local)) {
                 if (!owner.members.includes(caller))
                     missing.push(owner.owner + ': caller is not an advertised canvas member');
-                for (const member of owner.members.filter(member => member !== caller))
-                    if (!canvasStore.list().some(name => canvasStore.remoteMembersOf(name).includes(member)))
-                        missing.push(owner.owner + ': missing direct operator link to receiver ' + member);
+                // #282 S3: no per-member link here; the owner's signed canvas is the return path.
+                if (owner.members.every(member => member === caller))
+                    missing.push(owner.owner + ': the canvas lists no receiving member besides the caller');
             }
         }
         return canvasFailure(team, owners, reason) + (missing.length === 0 ? '' : ' — missing prerequisites: ' + missing.join('; '));
@@ -3368,7 +3257,6 @@ export function apply(ctx, config) {
     const forwardDirect = createDirectForward({
         births: forwardingBirths,
         enabled: () => config.forwardDirect === true, isolated: () => config.isolated, deposited: handle => cliDeposits.get(handle) !== undefined,
-        memberLinked: handle => canvasStore.list().some(name => canvasStore.remoteMembersOf(name).includes(handle)),
         scope: (handle, team) => config.teamScopeRouting ? outboundScope(senderScopeRecords, handle, handle, team) : Promise.resolve({ ok: true }),
         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),
@@ -3400,6 +3288,12 @@ export function apply(ctx, config) {
         // node team when it has joined, else the node label), so the receiver
         // can answer with one a2a_route instead of an unroutable display label.
         a2aJoinGateRefusal(agent === undefined ? undefined : { agent });
+        // #282 S2: an owner-qualified canvas id. Our own fingerprint is our canvas; a foreign one never
+        // lands on a same-named local canvas, and the directory walk keeps only that owner.
+        const ownerQualified = splitCanvasOwner(String(args.team ?? '').trim());
+        const foreignOwner = ownerQualified.owner !== undefined && ownerQualified.owner !== ownCanvasFingerprint ? ownerQualified.owner : undefined;
+        if (ownerQualified.owner !== undefined)
+            args = { ...args, team: ownerQualified.team };
         // A target-authored receipt attempt answers its own work even if scope/transport later refuses delivery.
         const answer = parseReceipt(args.message);
         if (agent !== undefined && answer !== null)
@@ -3472,7 +3366,7 @@ export function apply(ctx, config) {
         const failures = [];
         if (signal?.aborted)
             return localRoute({ ok: false, error: 'route aborted before dispatch', code: -32000 });
-        const outcome = await dispatchLocalCandidate(args.team, args.message, callerSession, args.context_id, signal, args.async === true, taskId, callbackAddress, agent === undefined ? undefined : String(agent.id));
+        const outcome = foreignOwner !== undefined ? undefined : await dispatchLocalCandidate(args.team, args.message, callerSession, args.context_id, signal, args.async === true, taskId, callbackAddress, agent === undefined ? undefined : String(agent.id));
         const localBirth = localBirths.get(taskId);
         localBirths.delete(taskId);
         if (outcome !== undefined) {
@@ -3493,7 +3387,7 @@ export function apply(ctx, config) {
         // union in member order. Non-canvas teams keep the single-walk shape
         // unchanged. The ledger stays keyed to the canvas team the caller
         // named; the peer request carries the member handle it must resolve.
-        const canvasName = parseCanvasTeamName(args.team);
+        const canvasName = foreignOwner !== undefined ? undefined : parseCanvasTeamName(args.team);
         // gh#131: one of this host's own handles is a local member, never a directory target.
         const remoteTargets = canvasName !== undefined ? ((resolve) => canvasStore.remoteMembersOf(canvasName).filter(ref => resolve(ref) === undefined))(localHandleResolver()) : [];
         const targets = remoteTargets.length > 0 ? [...remoteTargets] : [args.team];
@@ -3509,7 +3403,7 @@ export function apply(ctx, config) {
         }
         const candidatePool = [];
         for (const target of targets) {
-            for (const candidate of await directoryPeerCandidates(fetch, target, failures, scopedCanvasCaller)) {
+            for (const candidate of await directoryPeerCandidates(fetch, ownerQualified.owner !== undefined && target === args.team ? `${target}@${ownerQualified.owner}` : target, failures, scopedCanvasCaller)) {
                 candidatePool.push({ candidate, target });
             }
         }
@@ -3593,7 +3487,7 @@ export function apply(ctx, config) {
         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 };
+            return { ok: false, error: queueRefusal, code: WIRE_ERROR_QUEUE_FULL, next: QUEUE_FULL_NEXT };
         }
         const canvasName = parseCanvasTeamName(team);
         // Issue #41 shape note: the caller label is the WIRE form (<zone>/<id8>
@@ -3978,14 +3872,18 @@ export function apply(ctx, config) {
         // (gh#8: a squatter two gossip hops away captured routes by naming
         // itself after the target). referralTeamResolution restores the legacy
         // whole-store basis for fleets mid-migration.
+        // #282 S2: `<canvas>@<fp8>` selects only the owner whose signed card key matches; no delegation walk.
+        const qualified = splitCanvasOwner(team);
+        team = qualified.team;
+        const ownerOk = (card) => qualified.owner === undefined || canvasOwnerFingerprint(card?.publicKey) === qualified.owner;
         const peers = resolutionPeers();
         const candidates = [];
-        const cards = await mapBounded(peers, CANDIDATE_CONCURRENCY, async (peer) => ({ peer, card: await fetch(peer) }));
+        const cards = (await mapBounded(peers, CANDIDATE_CONCURRENCY, async (peer) => ({ peer, card: await fetch(peer) }))).map(entry => ownerOk(entry.card) ? entry : { peer: entry.peer, card: undefined });
         // 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 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) }));
+        const resolutions = qualified.owner !== undefined ? [] : 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`);
             return [];
@@ -4074,7 +3972,7 @@ export function apply(ctx, config) {
                     const card = await fetch(candidate);
                     peerAsync = card?.capabilities?.async === true;
                 }
-                const result = await dispatchPeerCandidate(candidate, request.handle, request.message, request.contextId, abort, session, request.delivery === 'async' && peerAsync, taskId, callbackAddress);
+                const result = await dispatchPeerCandidate(candidate, splitCanvasOwner(request.handle).team, request.message, request.contextId, abort, session, request.delivery === 'async' && peerAsync, taskId, callbackAddress);
                 if (!result.ok) {
                     // Idempotency verdicts (B3) are terminal, not failover: a replay
                     // says the prior attempt at THIS peer stays authoritative —
@@ -4107,7 +4005,7 @@ export function apply(ctx, config) {
                         break;
                     continue;
                 }
-                trackOwedTask(taskId, request.handle, candidate, result, callbackAddress, briefOf(request.message), sender, await peerBirth(fetch, candidate, undefined));
+                trackOwedTask(taskId, splitCanvasOwner(request.handle).team, candidate, result, callbackAddress, briefOf(request.message), sender, await peerBirth(fetch, candidate, undefined));
                 const contextId = request.contextId ?? (result.context_id !== '' ? result.context_id : `ctx-${Math.random().toString(16).slice(2, 10)}`);
                 if (result.task_status === 'TASK_STATE_COMPLETED') {
                     return { kind: 'completed', text: result.reply, taskId, contextId };