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

package/lib/task-auth.js

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

package/lib/task-ledger.js

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

package/lib/team-store.js

@@ -10,7 +10,7 @@
  * fresh by the state route.
  * @module @nelsonlongxiang/dsh-open-a2a-net/team-store
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 /** Upper bounds: a curation surface, not a database. */
 export const TEAM_NODE_CAP = 64;
@@ -115,6 +115,54 @@ export class TeamMembershipStore {
             this.notify();
         }
     }
+    /** One atomic roster replacement for the owner's workbench gesture. A failed disk write changes no in-memory membership. */
+    replaceTeam(team, members) {
+        const clean = validTeam(team);
+        if (clean === undefined || new Set(members).size !== members.length || members.some(id => id === ''))
+            return { ok: false, error: 'invalid roster team or member ids' };
+        if (this.membersOf(clean).join('\0') === members.join('\0'))
+            return { ok: true };
+        const wanted = new Set(members);
+        const next = this.entries.map(entry => ({ session: entry.session, teams: wanted.has(entry.session) ? [...entry.teams] : entry.teams.filter(t => t !== clean) }))
+            .filter(entry => entry.teams.length > 0);
+        for (const id of members) {
+            let entry = next.find(row => row.session === id);
+            if (entry === undefined) {
+                if (next.length >= TEAM_NODE_CAP)
+                    return { ok: false, error: 'roster node capacity reached' };
+                entry = { session: id, teams: [] };
+                next.push(entry);
+            }
+            if (!entry.teams.includes(clean)) {
+                if (entry.teams.length >= TEAMS_PER_NODE_CAP)
+                    return { ok: false, error: `session ${id} reached the team limit` };
+                entry.teams.push(clean);
+            }
+        }
+        try {
+            if (this.path !== '') {
+                mkdirSync(dirname(this.path), { recursive: true });
+                const tmp = `${this.path}.${String(process.pid)}.tmp`;
+                try {
+                    writeFileSync(tmp, JSON.stringify({ memberships: next }), { mode: 0o600 });
+                    renameSync(tmp, this.path);
+                }
+                catch (error) {
+                    try {
+                        unlinkSync(tmp);
+                    }
+                    catch { /* the original snapshot stays */ }
+                    throw error;
+                }
+            }
+        }
+        catch (error) {
+            return { ok: false, error: `roster persistence failed: ${String(error)}` };
+        }
+        this.entries = next;
+        this.notify();
+        return { ok: true };
+    }
     /** Drop every declaration of one session (a left or archived node). */
     dropSession(session) {
         const before = this.entries.length;

package/lib/tools/info.js

@@ -480,12 +480,14 @@ export function createInfoTools(deps) {
                                     deadAt: { type: 'number' },
                                     direction: { type: 'string', enum: ['inbound', 'outbound'] },
                                     receiptExpected: { type: 'boolean' },
+                                    forwarded: { type: 'boolean' },
+                                    deliveredTo: { type: 'string' },
                                     reason: { type: 'string', enum: ['fire-forget', 'unconsumed'] },
                                     sender: {
                                         type: 'object',
                                         additionalProperties: false,
                                         properties: {
-                                            kind: { type: 'string', required: true, enum: ['session', 'host', 'bridge'] },
+                                            kind: { type: 'string', required: true, enum: ['session', 'host', 'bridge', 'cli'] },
                                             id: { type: 'string', required: true },
                                             face: { type: 'string' },
                                         },
@@ -506,11 +508,12 @@ export function createInfoTools(deps) {
                                     resolvedAt: { type: 'number', required: true },
                                     summary: { type: 'string' },
                                     brief: { type: 'string' },
+                                    forwarded: { type: 'boolean' },
                                     sender: {
                                         type: 'object',
                                         additionalProperties: false,
                                         properties: {
-                                            kind: { type: 'string', required: true, enum: ['session', 'host', 'bridge'] },
+                                            kind: { type: 'string', required: true, enum: ['session', 'host', 'bridge', 'cli'] },
                                             id: { type: 'string', required: true },
                                             face: { type: 'string' },
                                         },
@@ -566,7 +569,20 @@ export function createInfoTools(deps) {
                 const archiveAll = taskLedger.archive();
                 return {
                     ok: true,
-                    tasks: taskLedger.list().map(task => ({ ...task })),
+                    // Project the declared fields only: ledger rows also carry internal audit facts (the #114 auth record,
+                    // #139 peerKey/peerHost) the output schema does not admit — spreading the row failed every call (0.6.32+).
+                    tasks: taskLedger.list().map(({ taskId, team, peer, startedAt, contextId, brief, status, deadAt, direction, receiptExpected, forwarded, deliveredTo, reason, sender }) => ({
+                        taskId, team, peer, startedAt, status,
+                        ...(contextId !== undefined ? { contextId } : {}),
+                        ...(brief !== undefined ? { brief } : {}),
+                        ...(deadAt !== undefined ? { deadAt } : {}),
+                        ...(direction !== undefined ? { direction } : {}),
+                        ...(receiptExpected !== undefined ? { receiptExpected } : {}),
+                        ...(forwarded !== undefined ? { forwarded } : {}),
+                        ...(deliveredTo !== undefined ? { deliveredTo } : {}),
+                        ...(reason !== undefined ? { reason } : {}),
+                        ...(sender !== undefined ? { sender } : {}),
+                    })),
                     archive: archiveAll.slice(0, 5).map(({ taskId, team, startedAt, resolvedAt, summary, brief, sender }) => ({ taskId, team, startedAt, resolvedAt, ...(summary !== undefined && summary !== '' ? { summary } : {}), ...(brief !== undefined ? { brief } : {}), ...(sender !== undefined ? { sender } : {}) })),
                     archivedTotal: archiveAll.length,
                 };

package/lib/types/a2a-client.d.ts

@@ -116,7 +116,7 @@ export declare class A2aClient {
      * @param callerSession - caller label overriding the node's label (the calling session's node label).
      * @returns the canonical route result (success or explicit failure).
      */
-    routeDirect(baseUrl: string, team: string, message: string, contextId?: string, signal?: AbortSignal, callerSession?: string, asyncMode?: boolean, taskIdFromCaller?: string, callbackAddress?: string): Promise<A2aRouteResult>;
+    routeDirect(baseUrl: string, team: string, message: string, contextId?: string, signal?: AbortSignal, callerSession?: string, asyncMode?: boolean, taskIdFromCaller?: string, callbackAddress?: string, guard?: string): Promise<A2aRouteResult>;
     /**
      * Query a peer's `/a2a/query` outcome surface (W7 slice 2): read-only
      * lookup of one claimed task's settled outcome. The fingerprint is the

package/lib/types/auth-observer.d.ts

@@ -49,7 +49,7 @@ export interface JudgedRow {
  * default: the birth record's `via`).
  * @returns the affected rows, in ledger order; unaffected rows are omitted.
  */
-export declare function judgeAffected(rows: readonly JudgedRow[], version: string, judge: (caller: string, target: string, ingress: 'wire' | 'local') => Admission, cacheResting?: (row: JudgedRow) => boolean): AffectedTask[];
+export declare function judgeAffected(rows: readonly JudgedRow[], version: string, judge: (caller: string, target: string, ingress: 'wire' | 'local', auth: TaskAuthorization) => Admission, cacheResting?: (row: JudgedRow) => boolean): AffectedTask[];
 /** What one {@link AuthObserver.observe} call needs from the host. */
 export interface ObserveInput {
     readonly version: string;
@@ -57,7 +57,7 @@ export interface ObserveInput {
     readonly inputs: () => unknown;
     readonly cause: string;
     readonly rows: () => readonly JudgedRow[];
-    readonly judge: (caller: string, target: string, ingress: 'wire' | 'local') => Admission;
+    readonly judge: (caller: string, target: string, ingress: 'wire' | 'local', auth: TaskAuthorization) => Admission;
 }
 /**
  * The persisted observer. One instance per host; every entry point is

package/lib/types/canvas-store.d.ts

@@ -22,6 +22,8 @@ export interface CanvasSnapshot {
         readonly name: string;
         readonly members: readonly string[];
     }>;
+    /** Pinned CLI handle -> linked home origin (only while some canvas team holds the handle). */
+    readonly cliHome?: Readonly<Record<string, string>>;
 }
 /** Upper bounds: a canvas taxonomy, not a database. */
 export declare const CANVAS_TEAM_CAP = 64;
@@ -50,6 +52,7 @@ export declare function validRemoteMemberRef(id: string): boolean;
 export declare class CanvasStore {
     /** Team entries in creation order; members in add order (routing priority). */
     private teams;
+    private cliHome;
     private readonly path;
     private readonly listeners;
     /**
@@ -74,6 +77,9 @@ export declare class CanvasStore {
     hasTeam(name: string): boolean;
     /** The named team's member ids in routing-priority order (a copy). */
     membersOf(name: string): readonly string[];
+    /** Frozen, operator-linked CLI home; undefined means unknown or ambiguous. */
+    cliHomeOf(handle: string): string | undefined;
+    pinnedCliHomes(): ReadonlyArray<readonly [string, string]>;
     /**
      * The named team's remote member refs (zone-qualified team handles) in
      * routing-priority order — the failover tier after the local live/cold
@@ -101,11 +107,14 @@ export declare class CanvasStore {
      * @param name - the existing team name.
      * @param id - the member session id.
      */
-    addMember(name: string, id: string): boolean;
+    addMember(name: string, id: string, home?: string, options?: {
+        replaceHome?: boolean;
+    }): boolean;
     /**
      * Remove one member from one team (a no-op when absent).
      */
     removeMember(name: string, id: string): boolean;
+    private forgetUnusedHome;
     /**
      * Drop one id from every team — the leave and archive paths: a session
      * leaving the network keeps no canvas membership anywhere.
@@ -113,3 +122,7 @@ export declare class CanvasStore {
      */
     dropMember(id: string): void;
 }
+/** One policy predicate for local and signed-remote canvas creation. */
+export declare function canvasNameReserved(raw: string, zone: string, allowlist: readonly string[], roster: {
+    membersOf(team: string): readonly string[];
+}): boolean;

package/lib/types/cli-home.d.ts

@@ -0,0 +1,24 @@
+import type { A2aPeerCard } from './types.ts';
+/** A verified, operator-linked host's full card at link time. */
+export interface CliHomeCandidate {
+    readonly url: string;
+    readonly linked: boolean;
+    readonly card?: A2aPeerCard;
+}
+/** Canonical root HTTP(S) origin; address aliases remain distinct trust decisions. */
+export declare function cliHomeOrigin(value: unknown): string | undefined;
+export type CliHomeDecision = {
+    readonly ok: true;
+    readonly home?: string;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** Read-only projection of the same fresh evidence used by explicit home validation. */
+export declare function cliHomeChoices(handle: string, candidates: readonly CliHomeCandidate[], locallyHeld?: boolean): {
+    homes: string[];
+    unreadable: number;
+    held?: true;
+};
+/** Count origins, not URL aliases: two card URLs on one host are one home. */
+export declare function decideCliHome(handle: string, requested: unknown, candidates: readonly CliHomeCandidate[], locallyHeld?: boolean): CliHomeDecision;

package/lib/types/client/A2aControl.d.ts

@@ -7,7 +7,7 @@ export interface A2aSessionRow {
 /** One routing outcome as the state route reports it. */
 export interface A2aActivityRow {
     readonly ts: number;
-    readonly dir: 'in' | 'out';
+    readonly dir: 'in' | 'out' | 'fwd';
     readonly team: string;
     readonly peer: string;
     readonly ok: boolean;

package/lib/types/direct-forward.d.ts

@@ -0,0 +1,32 @@
+import { type TaskLedger } from './task-ledger.ts';
+import type { A2aPeerCard, A2aRouteResult } from './types.ts';
+export interface ForwardRequest {
+    team: string;
+    message: string;
+    caller: string;
+    taskId: string;
+    contextId?: string;
+    noWait: boolean;
+    localCliProof: boolean;
+    guarded: boolean;
+}
+export interface DirectForwardDeps {
+    enabled(): boolean;
+    isolated(): boolean;
+    deposited(handle: string): boolean;
+    memberLinked(handle: string): boolean;
+    scope(handle: string, team: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    candidates(team: string, failures: string[], caller: string): Promise<{
+        urls: string[];
+        card(url: string): Promise<A2aPeerCard | undefined>;
+    }>;
+    dispatch(url: string, request: ForwardRequest, guard: string): Promise<A2aRouteResult>;
+    ledger: TaskLedger;
+    activity(team: string, peer: string, ok: boolean): void;
+}
+export declare function createDirectForward(d: DirectForwardDeps): (request: ForwardRequest) => Promise<A2aRouteResult>;

package/lib/types/faces/admin.d.ts

@@ -6,12 +6,13 @@ import type { Config } from '../index.ts';
 import type { CardCacheEntry, InFlightRoute, RouteActivityEntry } from '../runtime.ts';
 import { CanvasStore } from '../canvas-store.ts';
 import { type CanvasNotifyDeps } from './canvas-notify.ts';
-import type { CliDepositStore } from '../cli-deposit.ts';
+import { type CliDepositStore } from '../cli-deposit.ts';
 import type { ExposureStore } from '../exposure-store.ts';
 import type { GroupStore } from '../group-store.ts';
 import type { IdempotencyStore } from '../idempotency-store.ts';
 import type { JoinedSessions } from '../joined-store.ts';
 import type { LayoutStore } from '../layout-store.ts';
+import type { CliHomeDecision } from '../cli-home.ts';
 import type { PeerStore } from '../peer-store.ts';
 import { type TaskLedger } from '../task-ledger.ts';
 import type { TeamMembershipStore } from '../team-store.ts';
@@ -61,6 +62,12 @@ export interface AdminFaceDeps extends Pick<CanvasNotifyDeps, 'verifyOriginClaim
     readonly cliDeposits: CliDepositStore;
     readonly groupStore: GroupStore;
     readonly canvasStore: CanvasStore;
+    readonly cliHomeForAdd: (handle: string, requested?: unknown) => Promise<CliHomeDecision>;
+    readonly cliHomeOptions: (handle: string) => Promise<{
+        homes: string[];
+        unreadable: number;
+        held?: true;
+    }>;
     readonly layoutStore: LayoutStore;
     readonly taskLedger: TaskLedger;
     /** #114 S6: observe (lazily) and return the /state `authorization` block. */
@@ -74,6 +81,7 @@ export interface AdminFaceDeps extends Pick<CanvasNotifyDeps, 'verifyOriginClaim
         team: string;
         id: string;
         ok: boolean;
+        actor?: string;
         reason?: string;
     }[];
     readonly reportRing: {

package/lib/types/faces/wire.d.ts

@@ -14,13 +14,14 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Context } from '@deepseek-ai/cordis';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import type WebServer from '@deepseek-ai/dsh-host-webserver';
-import type { A2aPeerCard } from '../types.ts';
+import type { A2aPeerCard, A2aRouteResult } from '../types.ts';
+import type { ForwardRequest } from '../direct-forward.ts';
 import { CanvasStore } from '../canvas-store.ts';
-import type { CliDepositStore } from '../cli-deposit.ts';
+import { type CliDepositStore } from '../cli-deposit.ts';
 import type { IdempotencyStore } from '../idempotency-store.ts';
 import type { JoinedSessions } from '../joined-store.ts';
 import { type TaskLedger } from '../task-ledger.ts';
-import { type Admission, type SettlementRefusal, type Settler } from '../task-auth.ts';
+import { type Admission, type RemoteCliProof, type SettlementRefusal, type Settler } from '../task-auth.ts';
 import type { Config } from '../index.ts';
 /**
  * #139 (design §4.4): add `settlement: {status:'refused', reason, task_id}`
@@ -51,6 +52,7 @@ export type RouteOutcome = {
 } | {
     ok: false;
     error: string;
+    localMiss?: true;
 };
 interface BridgeTeamsRegistryMirror {
     listTeams(): Array<{
@@ -120,12 +122,17 @@ export interface WireDeps {
     readonly config: Config;
     readonly cliDeposits: CliDepositStore;
     readonly canvasStore: CanvasStore;
+    readonly canvasNameReserved: (name: string) => boolean;
     readonly sessionNodes: Map<string, Agent>;
     readonly joinedSessions: JoinedSessions;
     readonly idempotencyStore: IdempotencyStore;
     readonly verifyOriginClaim: (req: IncomingMessage, options?: {
         readonly cli?: boolean;
     }) => Promise<OriginClaimResult>;
+    readonly forwardDirect: (request: ForwardRequest) => Promise<A2aRouteResult>;
+    readonly remoteCliProof: (handle: string, claim: Extract<OriginClaimResult, {
+        ok: true;
+    }>) => Promise<RemoteCliProof | undefined>;
     readonly callerLinkedToThisHost: (caller: string, callerUrl: string, callerCard: A2aPeerCard | undefined) => boolean;
     /** This host's own card URL (read when a request lands; set once the web server settles). */
     readonly ownCardUrl: string;
@@ -134,7 +141,7 @@ export interface WireDeps {
     readonly secretEqual: (a: string, b: string) => boolean;
     readonly a2aCallerRefusal: (caller: string, targetTeam?: string) => string | undefined;
     /** #114 S2: the same decision with the rule and basis that admitted the caller. */
-    readonly a2aCallerAdmission: (caller: string, targetTeam?: string) => Admission;
+    readonly a2aCallerAdmission: (caller: string, targetTeam?: string, cliProof?: RemoteCliProof) => Admission;
     /** #114 S2: this host's allowlist version right now (design §2.3). */
     readonly allowlistVersionNow: () => string;
     /** #114 S6: record the version if it moved and re-judge affected tasks (observe only). */
@@ -158,6 +165,8 @@ export interface WireDeps {
     };
     readonly taskLedger: TaskLedger;
     readonly refuseIfFlooded: (caller: string, message: string, team: string, taskId: string, res: ServerResponse) => boolean;
+    /** gh#224: refuses a new delivery once the target already owes `targetQueueCap` receipts. */
+    readonly refuseIfQueueFull: (caller: string, message: string, team: string, taskId: string, mailbox: boolean, res: ServerResponse) => boolean;
     /** Settles a receipt; returns the enforce refusal of the row its header names (#139), if any. */
     readonly settleAndAnnounce: (message: string, settler?: Settler) => SettlementRefusal | undefined;
     readonly touchWakeDemand: () => void;

package/lib/types/index.d.ts

@@ -91,6 +91,8 @@ export interface Config {
      * (which is left untouched). Inbound faces keep answering. Default false.
      */
     readonly isolated: boolean;
+    /** Forward online local CLI deliveries one hop after a local miss. Default off. */
+    readonly forwardDirect: boolean;
     /** Human-facing name published on the agent card. */
     readonly agentName: string;
     /**
@@ -258,6 +260,8 @@ export interface Config {
      * v0.5.23 (async-stall): see the schema comment on asyncNudgeDelayMs.
      */
     readonly asyncNudgeDelayMs: number;
+    /** gh#224: receipt-owing tasks one target may queue on this host before new deliveries are refused (0 = off). */
+    readonly targetQueueCap: number;
     /**
      * How long the state route serves the cold-row id set from cache before
      * re-enumerating the persistence layer. The panel polls every 2s; the

package/lib/types/outbound-scope.d.ts

@@ -0,0 +1,21 @@
+/** One sender scope gate shared by model routing and home-host CLI forwarding. */
+export interface OutboundScopeRecords {
+    readonly zone: string;
+    teamsOf(id: string): readonly string[];
+    membersOf(team: string): readonly string[];
+    id8(id: string): string;
+    canvasNames(): readonly string[];
+    canvasMembers(name: string): readonly string[];
+    canvasTeam(name: string): string;
+    peerOrgs(): Iterable<readonly {
+        team?: unknown;
+        members?: unknown;
+    }[]>;
+    warmPeers(): Promise<unknown>;
+}
+export declare function outboundScope(r: OutboundScopeRecords, id: string, handle: string, team: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;

package/lib/types/queue-guard.d.ts

@@ -0,0 +1,32 @@
+/** gh#224 per-target queue cap (owner 2026-11-03: "at most 3 queued"). The flood guard (gh#91)
+ * bounds a sender's RATE; a slow, steady sender can still pile a dozen unanswered tasks onto one
+ * busy session. This counts what the target already owes and refuses a NEW delivery once the
+ * count reaches the cap, visibly and before anything is steered or booked.
+ *
+ * Counted ("queued for T"): rows this host's ledger still holds pending for T that expect a
+ * receipt — inbound rows born at /a2a/direct (addressed to T, or delivered to T), and same-host
+ * routes (peer 'local') to T. Never refused: a receipt for a task this host's ledger holds
+ * (terminal; refusing one strands that row — a genuine receipt always returns to the host that
+ * booked its task, so a '[A2A receipt]' header naming an unknown id is ordinary traffic and is
+ * counted), and deliveries into a CLI mailbox (its own 64-mail bound applies). A canvas team is
+ * one target: a full queue refuses the team as addressed, remote members included.
+ */
+import type { ServerResponse } from 'node:http';
+import type { IdempotencyStore } from './idempotency-store.ts';
+export declare const WIRE_ERROR_QUEUE_FULL = -32009;
+export declare const DEFAULT_TARGET_QUEUE_CAP = 3;
+/** The ledger fields the count reads. */
+export interface QueueRow {
+    readonly team: string;
+    readonly peer: string;
+    readonly status: string;
+    readonly direction?: string;
+    readonly receiptExpected?: boolean;
+    readonly deliveredTo?: string;
+}
+/** How many receipt-owing tasks this host holds pending for `team`. */
+export declare function queuedFor(rows: readonly QueueRow[], team: string): number;
+/** The refusal text when `team`'s queue is full, else undefined. `cap <= 0` disables the guard. */
+export declare function queueFullRefusal(rows: readonly QueueRow[], team: string, message: string, cap: number, mailbox: boolean, ownTask: (taskId: string) => boolean): string | undefined;
+/** Wire-face adapter in the flood guard's shape: a refused fresh key is FAILED, not stranded pending. */
+export declare function createQueueGuard(rows: () => readonly QueueRow[], cap: () => number, ownTask: (taskId: string) => boolean, outcomes: Pick<IdempotencyStore, 'recordOutcome'>, recordActivity: (dir: 'in' | 'out', team: string, peer: string, ok: boolean) => void): (caller: string, message: string, team: string, taskId: string, mailbox: boolean, res: ServerResponse) => boolean;

package/lib/types/roster-op.d.ts

@@ -0,0 +1,21 @@
+import { type TeamMembershipStore } from './team-store.ts';
+export interface RosterOpDeps {
+    zone: string;
+    home: string;
+    store: TeamMembershipStore;
+    joined: (id: string) => boolean;
+    canvasExists: (name: string) => boolean;
+    allowlist: () => readonly string[];
+    setAllowlist: (list: string[]) => void;
+    audit: (action: 'join' | 'leave', team: string, id: string, ok: boolean, reason: string) => void;
+}
+export type RosterOpResult = {
+    ok: true;
+    team: string;
+    members: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/** Writes complete snapshots; on a failed second write, rolls the first back. */
+export declare function rosterOp(d: RosterOpDeps, raw: unknown): RosterOpResult;

package/lib/types/runtime.d.ts

@@ -11,7 +11,7 @@ import type { A2aPeerCard } from './types.ts';
  */
 export interface RouteActivityEntry {
     readonly ts: number;
-    readonly dir: 'in' | 'out';
+    readonly dir: 'in' | 'out' | 'fwd';
     readonly team: string;
     readonly peer: string;
     readonly ok: boolean;