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

package/lib/index.js

@@ -5,9 +5,10 @@
  * 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 { selectLanIPv4 } from "./lan-ip.js";
 import { dirname, join } from 'node:path';
 import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
 // The package own version, read from package.json at load time so the
@@ -26,7 +27,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 +44,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 +81,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.
@@ -342,6 +226,11 @@ export function apply(ctx, config) {
         const site = req.headers['sec-fetch-site'];
         if (typeof site === 'string' && site !== 'same-origin' && site !== 'none')
             return false;
+        // A reverse proxy or tunnel on this host (Caddy, nginx, a tunnel agent) reaches us over loopback for EVERY
+        // remote client: a forwarding header says the real caller is elsewhere, so loopback trust does not apply —
+        // otherwise the workbench shell would hand the apiKey to anyone on the internet. Forging one only denies trust.
+        if (req.headers['x-forwarded-for'] !== undefined || req.headers.forwarded !== undefined || req.headers['x-real-ip'] !== undefined)
+            return false;
         const remote = req.socket.remoteAddress;
         return remote === '127.0.0.1' || remote === '::1' || remote === '::ffff:127.0.0.1';
     }
@@ -564,6 +453,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 = '';
     /**
@@ -652,20 +543,12 @@ export function apply(ctx, config) {
             recentActivity.splice(0, recentActivity.length - ACTIVITY_CAP);
     };
     /**
-     * This host's primary LAN IPv4 (first non-internal address), computed once:
+     * This host's primary LAN IPv4 (RFC1918 > other external IPv4 > CGNAT), computed once:
      * a node fact the card and state route publish so peers and operators can
      * tell machines apart in a same-team fleet. Empty when no external address
      * exists (loopback-only deployments).
      */
-    const lanIp = (() => {
-        for (const entries of Object.values(networkInterfaces())) {
-            for (const entry of entries ?? []) {
-                if (entry.family === 'IPv4' && !entry.internal)
-                    return entry.address;
-            }
-        }
-        return '';
-    })();
+    const lanIp = selectLanIPv4(networkInterfaces());
     // Session groups: user-named buckets for the panel's session listing,
     // persisted beside the join intents so they survive restarts.
     // Deprecated as of 0.6.6 — canvas teams are the grouping face now; this
@@ -1360,7 +1243,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 +1259,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 +1564,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 +1736,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;
         }
     }
@@ -2189,8 +2073,20 @@ export function apply(ctx, config) {
      */
     function routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom, onSteered) {
         return new Promise((resolve) => {
+            const floorAtRegistration = sessionEventsOf(agent).length;
             const waiter = registerFinalWaiter(agent, (text, placeholder) => {
-                resolve({ ok: true, reply: text, ...(placeholder === true ? { placeholder: true } : {}) });
+                // #298 (review of #305 F4): the sync wait may close on a busy target's OTHER turn. `ownTurn` states,
+                // from this session's own events, that the steer carrying this task was read and that the reply is the
+                // reading turn's own last text — the only reply a peer may declare final (`reply_final`).
+                let ownTurn = false;
+                if (placeholder !== true && taskId !== undefined && taskId !== '') {
+                    const events = sessionEventsOf(agent);
+                    const read = consumptionIndex(events, taskId, floorAtRegistration);
+                    // The receipt's own window (review of #305 F5): a back-to-back next turn's text is not this turn's.
+                    const window = read === undefined ? undefined : readingTurnReply(events, read);
+                    ownTurn = window !== undefined && window.completed && window.reply !== '' && window.reply === text;
+                }
+                resolve({ ok: true, reply: text, ...(placeholder === true ? { placeholder: true } : {}), ...(ownTurn ? { ownTurn: true } : {}) });
             });
             // The header names the sender first: `caller` is the routing node's
             // own label (the session that issued the route), while `team` is this
@@ -2593,7 +2489,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,
@@ -2875,7 +2772,7 @@ export function apply(ctx, config) {
      */
     function peerLinkState(peerUrl) {
         return peerLinkDisplay(peerUrl, {
-            card: cardCache.get(peerUrl)?.card, ownUrl: ownCardUrl, seeds: config.peers,
+            card: cardCache.get(peerUrl)?.card, ownUrl: ownCardUrl, ownAudiences: config.originClaimAudiences, seeds: config.peers,
             refs: canvasStore.list().flatMap(name => [...canvasStore.remoteMembersOf(name)]),
             ownHandles: new Set([...joinedSessions.list(), ...liveRoots.keys()].map(id => `${config.team}/${id8(id)}`)),
             cards: [...cardCache.values()].flatMap(entry => entry.card === undefined ? [] : [entry.card]),
@@ -3297,6 +3194,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 +3211,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 +3257,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 +3267,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 +3298,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 +3376,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 +3397,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 +3413,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 +3497,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 +3882,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 +3982,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 +4015,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 };
@@ -4260,24 +4168,14 @@ export function apply(ctx, config) {
                     entry.scannedTo = events.length;
                     continue;
                 }
-                // The consuming turn's window: up to its own `turn/end`, never into a
-                // following turn (back-to-back turns can run with no idle between).
-                // Without turn markers, this idle is the turn's end.
-                let end = events.length;
-                let completed = true;
-                if (turnMarked) {
-                    const close = turnEndIndex(events, entry.consumedAt + 1);
-                    if (close === undefined) {
-                        // The consuming turn is still open: wait for its turn/end.
-                        continue;
-                    }
-                    end = close;
-                    completed = events[close]?.data?.reason?.kind === 'completed';
-                }
+                const window = readingTurnReply(events, entry.consumedAt, turnMarked);
+                // The consuming turn is still open: wait for its turn/end.
+                if (window === undefined)
+                    continue;
                 // The waiter closes HERE with that turn's last text. A turn that said
                 // nothing, or ended aborted/failed/blocked, did no work this host can
                 // vouch for: close as a placeholder — no receipt, the row stays owed.
-                const reply = latestAssistantText(events, entry.consumedAt + 1, end);
+                const { reply, completed } = window;
                 answered.push(reply !== '' && completed ? { entry, reply } : { entry, reply: '', placeholder: true });
                 continue;
             }
@@ -4300,6 +4198,20 @@ export function apply(ctx, config) {
                 entry.answer(reply);
         }
     }
+    /**
+     * #114 S5: the consuming turn's window — from the read at `read` up to its own `turn/end`, never into a
+     * following turn (back-to-back turns can run with no idle between); without turn markers, up to now (the
+     * idle is the turn's end). Undefined while a marked turn is still open. The receipt waiter and the sync
+     * answer's `ownTurn` (#298) both read this one window.
+     */
+    function readingTurnReply(events, read, turnMarked = events.some(event => event?.type === 'turn/start' || event?.type === 'turn/end')) {
+        if (!turnMarked)
+            return { reply: latestAssistantText(events, read + 1), completed: true };
+        const close = turnEndIndex(events, read + 1);
+        if (close === undefined)
+            return undefined;
+        return { reply: latestAssistantText(events, read + 1, close), completed: events[close]?.data?.reason?.kind === 'completed' };
+    }
     /** #114 S5: the index of the first `turn/end` at or after `from`, or undefined while the turn is open. */
     function turnEndIndex(events, from) {
         for (let index = from; index < events.length; index++) {

package/lib/lan-ip.js

@@ -0,0 +1,20 @@
+/** #311: prefer LAN addresses over overlay CGNAT without depending on adapter names. */
+import { isIPv4 } from 'node:net';
+/** RFC1918 > other external IPv4 > CGNAT (100.64/10); ties retain enumeration order. */
+export function selectLanIPv4(interfaces) {
+    let selected = '', best = Infinity;
+    for (const entries of Object.values(interfaces)) {
+        for (const entry of entries ?? []) {
+            if (entry.family !== 'IPv4' || entry.internal || !isIPv4(entry.address))
+                continue;
+            const [a, b] = entry.address.split('.').map(Number);
+            const rank = a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168)
+                ? 0 : a === 100 && b >= 64 && b <= 127 ? 2 : 1;
+            if (rank < best) {
+                selected = entry.address;
+                best = rank;
+            }
+        }
+    }
+    return selected;
+}

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

@@ -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-link-display.js

@@ -8,8 +8,9 @@ export function peerLinkDisplay(peerUrl, d) {
     catch {
         return '';
     } };
-    const peerOrigin = origin(peerUrl), ownOrigin = origin(d.ownUrl);
-    const bilateral = peerOrigin !== '' && ownOrigin !== '' && d.seeds.some(url => origin(url) === peerOrigin) && (card.peers ?? []).some(url => origin(url) === ownOrigin);
+    const peerOrigin = origin(peerUrl);
+    const ownOrigins = new Set([d.ownUrl, ...d.ownAudiences ?? []].map(origin).filter(value => value !== ''));
+    const bilateral = peerOrigin !== '' && d.seeds.some(url => origin(url) === peerOrigin) && (card.peers ?? []).some(url => ownOrigins.has(origin(url)));
     const exactMember = d.refs.some(ref => !d.ownHandles.has(ref) && (card.sessionTeams ?? []).some(row => row.team === ref) && !d.cards.some(other => other.publicKey !== card.publicKey && (other.sessionTeams ?? []).some(row => row.team === ref)));
     return { link: bilateral || exactMember ? 'linked' : 'stranger', verified: true };
 }

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;