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

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,36 +26,37 @@ 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";
 import { LayoutStore } from "./layout-store.js";
 import { peerLinkDisplay } from "./peer-link-display.js";
+import { canvasOwners, canvasFailure } from "./canvas-discovery.js";
 import { JoinedSessions } from "./joined-store.js";
 import { ExposureStore } from "./exposure-store.js";
 import { loadSeatNames } from "./owner-settings.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 { 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";
@@ -79,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(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([]),
-    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.
@@ -563,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 = '';
     /**
@@ -682,7 +568,13 @@ export function apply(ctx, config) {
     // queryable here, and the correlating `[A2A receipt] task <id>` message
     // resolves it — the caller-side half of the receipt contract, persisted so
     // a restart does not orphan the reconciliation.
-    const taskLedger = new TaskLedger(join(home, 'a2a', 'tasks.json'), { staleTtlMs: config.taskStaleTtlMs });
+    const taskLedger = new TaskLedger(join(home, 'a2a', 'tasks.json'), { staleTtlMs: config.taskStaleTtlMs, warn: message => logger.warn(message) });
+    const enforceBlockers = taskLedger.settlementEnforceBlockers();
+    const enforceRefused = config.settlementAuth === 'enforce' && enforceBlockers.length > 0 ? { reason: 'legacy forwarded canvas debts lack receiver facts', blockers: enforceBlockers } : undefined;
+    if (enforceRefused !== undefined) {
+        logger.error('settlementAuth enforce refused; running observe (#125/#275): %s', JSON.stringify(enforceRefused));
+        config = { ...config, settlementAuth: 'observe' };
+    }
     // Unjoined-node reporting ingress (design: docs/design/unjoined-report-ingress.md):
     // a one-way signal channel for sessions with no network membership — a
     // fallen-off or never-joined session reports "I exist / I have a task"
@@ -727,6 +619,12 @@ export function apply(ctx, config) {
      * the consumer's own discipline — keep seam listeners synchronous.
      * @param message - the inbound or relayed message text.
      */
+    const forwardingBirths = new ForwardBirths();
+    async function waitForForwardBirth(message) {
+        const receipt = parseReceipt(message);
+        if (receipt !== null)
+            await forwardingBirths.wait(receipt.taskId);
+    }
     function settleAndAnnounce(message, settler) {
         const parsedForJudge = parseReceipt(message);
         const judge = settlementJudgeFor(settler, parsedForJudge);
@@ -1347,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)))
@@ -1362,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);
@@ -1660,13 +1559,14 @@ export function apply(ctx, config) {
             // gh#77 B1: the admin faces live in src/faces/admin.ts.
             registerAdminFaces(webServer, {
                 ctx, config, logger, home, session, lanIp, PLUGIN_VERSION, controlRoute, controlTrustedWithoutKey, readJsonBody, peerFetch, peerStore, peerLinkState, originClaimHeaders, refreshRemoteRows, joinedSessions, exposureStore, teamMemberships, cliDeposits, groupStore, canvasStore, cliHomeForAdd, cliHomeOptions, layoutStore, taskLedger, idempotencyStore, inFlightRoutes, recentActivity, teamAuditRing, reportRing, sessionNodes, liveRoots, mountSessionNode, coldJoinedIds, prewarmStatus, reconcileStatus, id8, sessionLabelOf, sessionTeamOf, ownCanvasHandleOf, localSessionOfHandle, canvasTeamsOfSession, nodeMetadataOf, canvasTeamOf, archivedSessionFilter, pruneArchivedJoins, pruneCanvasMemberships, verifyOriginClaim, callerLinkedToThisHost, cachedCardFetch, authorizationView,
-                indexUrl: import.meta.url,
+                indexUrl: import.meta.url, enforceRefused,
                 get cardCache() { return cardCache; },
                 get remoteRowsCache() { return remoteRowsCache; },
                 get legacyInboundCount() { return legacyInboundCount; },
                 get unboundInboundCount() { return unboundInboundCount; },
                 get boundMissInboundCount() { return boundMissInboundCount; },
-                get ownCardUrl() { return ownCardUrl; },
+                get boundMissRecent() { return boundMissRecent; },
+                get ownCardUrl() { return ownCardUrl; }, ownCanvasFingerprint,
                 get ownerSeatNames() { return ownerSeatNames; },
                 set ownerSeatNames(v) { ownerSeatNames = v; },
                 get ownerAllowlist() { return ownerAllowlist; },
@@ -1838,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;
         }
     }
@@ -2121,15 +2021,15 @@ export function apply(ctx, config) {
      * marker instead of a (false) completion.
      * @param taskId - the correlation key the steered receipt header carries.
      */
-    async function routeIntoAgent(team, message, caller, taskId, proofClause, buildHeader, localFrom) {
+    async function routeIntoAgent(team, message, caller, taskId, proofClause, buildHeader, localFrom, onSteered) {
         const agent = resolveAgentForTeam(team) ?? canvasLiveAgent(parseCanvasTeamName(team));
         if (agent !== undefined) {
-            return routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom);
+            return routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom, onSteered);
         }
         // Wake-on-route: a cold joined team materializes on demand, then steers.
         const wake = wakeColdTeam(team);
         if (wake.kind === 'flight') {
-            return wake.flight.then(agent => routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom), (error) => ({ ok: false, error: `waking the session for team "${team}" failed: ${String(error)}` }));
+            return wake.flight.then(agent => routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom, onSteered), (error) => ({ ok: false, error: `waking the session for team "${team}" failed: ${String(error)}` }));
         }
         // Native-teams inbound bridge (opt-in): a registry team claims the
         // handle and dispatches through its authoritative seam. Checked before
@@ -2158,7 +2058,7 @@ export function apply(ctx, config) {
             if (live !== undefined) {
                 if (callerIsAgent(live, caller))
                     return { ok: false, error: selfRouteText(team) };
-                return routeIntoAgentFor(live, team, message, caller, taskId, proofClause, buildHeader);
+                return routeIntoAgentFor(live, team, message, caller, taskId, proofClause, buildHeader, undefined, onSteered);
             }
             return { ok: false, error: 'No live DSH agent is available to accept this message.' };
         }
@@ -2173,7 +2073,7 @@ export function apply(ctx, config) {
      * @param caller - caller label for the steered prefix.
      * @returns the agent's final reply, or the explicit failure.
      */
-    function routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom) {
+    function routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom, onSteered) {
         return new Promise((resolve) => {
             const waiter = registerFinalWaiter(agent, (text, placeholder) => {
                 resolve({ ok: true, reply: text, ...(placeholder === true ? { placeholder: true } : {}) });
@@ -2190,7 +2090,11 @@ export function apply(ctx, config) {
                 : `[A2A direct] ${taskId === undefined ? '' : `(task ${taskId}) `}未验证（in-process） ${sanitizeFromClause(from)} (routed to ${team}) sent:`;
             const text = `${headerLine}\n\n${message}`;
             try {
+                const floor = sessionEventsOf(agent).length;
                 steerRelay(agent, text, caller === '' ? undefined : caller, localFrom);
+                onSteered?.(agent, floor);
+                if (onSteered !== undefined && sessionEventsOf(agent).slice(floor).some(event => event?.type === 'assistant/message'))
+                    queueMicrotask(() => flushFinals(String(agent.id))); // synchronous final may already have emitted idle
             }
             catch (error) {
                 // The waiter was registered above, so the key always holds it; the
@@ -2223,6 +2127,15 @@ export function apply(ctx, config) {
      *  closing originClaimUnboundWindow; boundMissInbound: those of them whose
      *  bound form missed (a peer dials us by a name not in our audiences). */
     let unboundInboundCount = 0, boundMissInboundCount = 0;
+    /** Which verified callers missed, and the origin they dialled: what to add to originClaimAudiences (#64). */
+    const boundMissRecent = [];
+    const noteBoundMiss = (miss) => {
+        boundMissInboundCount += 1;
+        const at = boundMissRecent.findIndex(row => row.caller === miss.caller && row.audience === miss.audience);
+        const row = at >= 0 ? boundMissRecent.splice(at, 1)[0] : { ...miss, count: 0, lastAt: 0 };
+        boundMissRecent.unshift({ ...row, count: row.count + 1, lastAt: Date.now() });
+        boundMissRecent.length = Math.min(boundMissRecent.length, 16);
+    };
     function verifyOriginClaim(req, options) {
         return verifyOriginClaimOf(req, {
             cardCache,
@@ -2230,7 +2143,7 @@ export function apply(ctx, config) {
             audiences: [ownCardUrl, ...config.originClaimAudiences ?? []],
             unboundOpen: config.originClaimUnboundWindow !== false,
             onUnbound: () => { unboundInboundCount += 1; },
-            onBoundMiss: () => { boundMissInboundCount += 1; },
+            onBoundMiss: noteBoundMiss,
             loopbackArrival: (config.originClaimUrl ?? '') === '',
             now: Date.now(),
             ...(options?.cli === true ? { cliDeposit: cliDepositCard } : {}),
@@ -2566,7 +2479,9 @@ 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,
             bumpLegacyInbound: () => { legacyInboundCount += 1; },
@@ -2580,7 +2495,7 @@ export function apply(ctx, config) {
             taskLedger,
             refuseIfFlooded,
             refuseIfQueueFull,
-            settleAndAnnounce,
+            settleAndAnnounce, waitForForwardBirth,
             touchWakeDemand: () => { lastWakeDemandAt = Date.now(); },
             session,
             resolveAgentForTeam,
@@ -3057,7 +2972,7 @@ export function apply(ctx, config) {
     };
     const SWEEP_CONCURRENCY = 6;
     const infoTools = createInfoTools({
-        ctx, config, logger, session, lanIp, ownCardUrl, peerStore, taskLedger,
+        ctx, config, logger, session, lanIp, get ownCardUrl() { return ownCardUrl; }, peerStore, taskLedger,
         inFlightRoutes, recentActivity, joinedSessions, sessionNodes, canvasStore,
         teamMemberships, exposureStore, idempotencyStore, cardCache,
         id8, sessionTeamOf,
@@ -3126,6 +3041,7 @@ export function apply(ctx, config) {
                     team: canvasTeamOf(name),
                     session,
                     name,
+                    kind: 'canvas', owner: ownCardUrl, memberCount: canvasStore.membersOf(name).length,
                     description: `canvas team — ${members.length} member${members.length === 1 ? '' : 's'}, ${live} live`,
                     local: true,
                     origin: localOrigin,
@@ -3268,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)}`),
@@ -3284,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).
@@ -3304,9 +3222,41 @@ export function apply(ctx, config) {
      * caller label — the "能发即能收" invariant: whatever it addresses can
      * answer it with one route.
      */
+    const knownCanvasOwners = () => canvasOwners(canvasStore.list().map(name => ({ name, team: canvasTeamOf(name), members: canvasStore.membersOf(name) })), ownCardUrl, [...cardCache.entries()].flatMap(([url, entry]) => entry.card === undefined ? [] : [{ url, card: entry.card }]));
+    const diagnoseCanvas = async (team, reason, caller) => {
+        if (!new RegExp('^.+/canvas/[^/]+$').test(team))
+            return reason;
+        try {
+            await listDirectoryTeams(false, true);
+        }
+        catch (error) {
+            return reason + ' — canvas discovery unavailable: ' + String(error);
+        }
+        const resolve = localHandleResolver();
+        const localId = caller === undefined ? undefined : resolve(caller);
+        const owners = knownCanvasOwners().filter(row => !ownerTeamScopeInfo || (caller !== undefined && cliDeposits.get(caller) !== undefined) || (row.local ? localId !== undefined && row.members.some(ref => ref === localId || resolve(ref) === localId) : (row.scopeMembers ?? row.members).some(ref => { const id = resolve(ref); return id !== undefined && joinedSessions.has(id); })));
+        const missing = [];
+        if (caller !== undefined && cliDeposits.get(caller) !== undefined) {
+            if (!config.forwardDirect)
+                missing.push('home forwardDirect is off');
+            if (config.isolated)
+                missing.push('home is isolated');
+            const scope = config.teamScopeRouting ? await outboundScope(senderScopeRecords, caller, caller, team) : { ok: true };
+            if (!scope.ok)
+                missing.push('sender scope: ' + scope.error);
+            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');
+                // #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('; '));
+    };
     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),
@@ -3338,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)
@@ -3363,7 +3319,7 @@ export function apply(ctx, config) {
                 scopedCanvasCaller = { id: scopeCaller, handle: callerHandle };
                 const scope = await outboundScope(senderScopeRecords, scopeCaller, callerHandle, String(args.team ?? '').trim());
                 if (!scope.ok)
-                    return localRoute(scope);
+                    return localRoute({ ...scope, error: await diagnoseCanvas(args.team, scope.error, callerHandle) });
             }
         }
         let callerSession = resolveCallerLabel({
@@ -3410,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) {
@@ -3431,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];
@@ -3447,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 });
             }
         }
@@ -3491,7 +3447,8 @@ export function apply(ctx, config) {
         }
         if (failures.length > 0)
             logger.warn(`route to team "${args.team}" exhausted its candidates: ${failures.join('; ')}`);
-        return routeVerdict(args.team, failures, candidatePool.length);
+        const verdict = routeVerdict(args.team, failures, candidatePool.length);
+        return { ...verdict, error: await diagnoseCanvas(args.team, verdict.error, callerSession) };
     }
     /**
      * The route dispatcher's local half: same-host candidates dial in-process,
@@ -3530,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>
@@ -3915,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 [];
@@ -4011,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 —
@@ -4044,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 };

package/lib/live-roots.js

@@ -0,0 +1,39 @@
+function safeDepth(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && !Object.is(value, -0)
+        ? value
+        : undefined;
+}
+/**
+ * Delegation depth of a live agent: 0 = top-level. Mirrors the harness'
+ * authoritative max(persisted session header, runtime options); invalid
+ * values read as absent (never throwing) — see the module comment.
+ */
+export function delegationDepthOf(agent) {
+    const carrier = agent;
+    return Math.max(safeDepth(carrier.options?.subagentDepth) ?? 0, safeDepth(carrier.session?.header?.delegationDepth) ?? 0);
+}
+/** Whether a live agent is top-level (not inside any subagent tree). */
+export function isTopLevelAgent(agent) {
+    return delegationDepthOf(agent) === 0;
+}
+/**
+ * Live top-level agents on this host: `roots()` where the host still has
+ * it (exact pre-0.2.2 semantics, so old hosts change nothing), else
+ * `list()` filtered by delegation depth. A missing registry, a surface
+ * with neither method, or a throwing method all degrade to `[]`.
+ */
+export function liveRootAgents(registry) {
+    if (registry === undefined || registry === null)
+        return [];
+    const surface = registry;
+    try {
+        if (typeof surface.roots === 'function')
+            return [...surface.roots()];
+        if (typeof surface.list === 'function')
+            return surface.list().filter(isTopLevelAgent);
+    }
+    catch {
+        return [];
+    }
+    return [];
+}

package/lib/origin-claim.js

@@ -210,7 +210,7 @@ export async function verifyOriginClaim(req, d) {
             return;
         d.onUnbound();
         if (hasBound)
-            d.onBoundMiss?.();
+            d.onBoundMiss?.({ caller, audience: originOf(audience) });
     };
     // gh#133: a CLI identity deposited HERE, decided from the deposit table
     // before any fetch (the CLI may reach its home through a proxy the host
@@ -224,7 +224,7 @@ export async function verifyOriginClaim(req, d) {
         if (cli.name !== caller)
             return { ok: false, reason: 'not-derivable' };
         accepted();
-        return { ok: true, caller: cli.handle, callerUrl, card: cli.card, bound, cli: true };
+        return { ok: true, caller: cli.handle, callerUrl, card: cli.card, bound, cli: true, ...(bound && hasBodySig ? { bodyBound: true } : {}) };
     }
     // Fetch the caller's card PLAIN (REVIEW M2 third-round ruling: the
     // envelope names a BARE ZONE, and derivation is the exact match
@@ -265,5 +265,6 @@ export async function verifyOriginClaim(req, d) {
     if (card.team !== caller)
         return { ok: false, reason: 'not-derivable' };
     accepted();
-    return { ok: true, caller, callerUrl, card, bound };
+    // #282 S3 review: a verified Sig3 means the body itself was signed (stripping it falls back to Sig2, which has no bodyBound).
+    return { ok: true, caller, callerUrl, card, bound, ...(bound && hasBodySig ? { bodyBound: true } : {}) };
 }

package/lib/peer-directory.js

@@ -109,7 +109,7 @@ export function peerDirectoryRows(card, peer, includeCanvas) {
     if (includeCanvas)
         for (const entry of advertisedCanvasTeams(card)) {
             const declared = rosterOf.get(entry.team);
-            rows.push({ team: entry.team, session: card.session, name: entry.name, description: 'canvas team', origin, via: peer, ...(legacy ? { legacy } : {}), ...(declared !== undefined && declared.length > 0 ? { teams: declared } : {}), canvasMembers: entry.members.filter(ref => !publishedSessions.has(ref)) });
+            rows.push({ team: entry.team, session: card.session, name: entry.name, description: 'canvas team', kind: 'canvas', owner: peer, memberCount: entry.members.length, origin, via: peer, ...(legacy ? { legacy } : {}), ...(declared !== undefined && declared.length > 0 ? { teams: declared } : {}), canvasMembers: entry.members.filter(ref => !publishedSessions.has(ref)) });
         }
     return rows;
 }

package/lib/queue-guard.js

@@ -21,6 +21,8 @@ export function queueFullRefusal(rows, team, message, cap, mailbox, ownTask) {
         return undefined;
     return `target-queue-full (gh#224): "${team}" already has ${String(queued)} task(s) not yet answered by the target (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.`;
 }
+/** #282 S1: the one next step for a full target queue. */
+export const QUEUE_FULL_NEXT = 'wait for a receipt from the target (a2a-net inbox / a2a_tasks), then send again with a new task id; do not resend in a loop';
 /** 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) => {
@@ -29,7 +31,7 @@ export function createQueueGuard(rows, cap, ownTask, outcomes, recordActivity) {
             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' });
+        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', next: QUEUE_FULL_NEXT });
         res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
         res.end(payload);
         return true;