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

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

@@ -1,4 +1,5 @@
-import { type TaskLedger } from './task-ledger.ts';
+import { type TaskLedger, type TaskRecord } from './task-ledger.ts';
+import { type TaskAuthorization } from './task-auth.ts';
 import type { A2aPeerCard, A2aRouteResult } from './types.ts';
 export interface ForwardRequest {
     team: string;
@@ -9,12 +10,27 @@ export interface ForwardRequest {
     noWait: boolean;
     localCliProof: boolean;
     guarded: boolean;
+    auth?: TaskAuthorization;
+}
+/** An early receipt waits at most this long for its forward row to be born (#298). */
+export declare const BIRTH_WAIT_CAP_MS = 60000;
+/** Birth barrier exists only for eligible, actively dispatched tasks; receipts never reserve a slot. */
+export declare class ForwardBirths {
+    private readonly waitCapMs;
+    private readonly pending;
+    constructor(waitCapMs?: number);
+    /**
+     * Resolves when the birth is released or after the cap, whichever is first. After the cap the receipt
+     * is judged by the normal rules against whatever row exists then — never accepted in advance (#298).
+     */
+    wait(taskId: string): Promise<void> | undefined;
+    begin(taskId: string): (() => void) | undefined;
 }
 export interface DirectForwardDeps {
+    births: ForwardBirths;
     enabled(): boolean;
     isolated(): boolean;
     deposited(handle: string): boolean;
-    memberLinked(handle: string): boolean;
     scope(handle: string, team: string): Promise<{
         ok: true;
     } | {
@@ -30,3 +46,18 @@ export interface DirectForwardDeps {
     activity(team: string, peer: string, ok: boolean): void;
 }
 export declare function createDirectForward(d: DirectForwardDeps): (request: ForwardRequest) => Promise<A2aRouteResult>;
+/**
+ * #282 S3 (same team authorizes): the admission basis for a receipt delivered to a local CLI mailbox
+ * from a member the home never linked — only for that CLI's own pending forward, only from a receiver
+ * frozen at birth, only when the body-bound (Sig3) claim's card key is the frozen peer key. Anything else:
+ * undefined. Trust assumption (design D2): the selected owner host is honest about its own canvas — it may
+ * list any label as a receiver, including one of this host's session labels in the same zone.
+ */
+export declare function forwardReceiptBasis(row: TaskRecord | undefined, caller: string, cliHandle: string, claim: {
+    readonly caller: string;
+    readonly bound: boolean;
+    readonly bodyBound?: true;
+    readonly card: {
+        readonly publicKey: string;
+    };
+}): string | undefined;

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

@@ -70,6 +70,10 @@ export interface AdminFaceDeps extends Pick<CanvasNotifyDeps, 'verifyOriginClaim
     }>;
     readonly layoutStore: LayoutStore;
     readonly taskLedger: TaskLedger;
+    readonly enforceRefused?: {
+        reason: string;
+        blockers: readonly string[];
+    };
     /** #114 S6: observe (lazily) and return the /state `authorization` block. */
     readonly authorizationView: () => unknown;
     readonly idempotencyStore: IdempotencyStore;
@@ -140,7 +144,15 @@ export interface AdminFaceDeps extends Pick<CanvasNotifyDeps, 'verifyOriginClaim
     readonly legacyInboundCount: number;
     readonly unboundInboundCount: number;
     readonly boundMissInboundCount: number;
+    readonly boundMissRecent: ReadonlyArray<{
+        caller: string;
+        audience: string;
+        count: number;
+        lastAt: number;
+    }>;
     readonly ownCardUrl: string;
+    /** #282 S2: this host's canvas owner fingerprint. */
+    readonly ownCanvasFingerprint: string;
     ownerSeatNames: Record<string, string>;
     ownerAllowlist: string[];
     ownerTeamScopeInfo: boolean;

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

@@ -111,6 +111,7 @@ export type OriginClaimResult = {
     card: A2aPeerCard;
     bound: boolean;
     cli?: true;
+    bodyBound?: true;
 } | {
     ok: false;
     reason: string;
@@ -131,9 +132,16 @@ export interface WireDeps {
         readonly rawBody?: Uint8Array;
     }) => Promise<OriginClaimResult>;
     readonly forwardDirect: (request: ForwardRequest) => Promise<A2aRouteResult>;
+    /** #282 S2: this host's canvas owner fingerprint. */
+    readonly ownCanvasFingerprint: string;
+    readonly diagnoseCanvas: (team: string, reason: string, caller?: string) => Promise<string>;
     readonly remoteCliProof: (handle: string, claim: Extract<OriginClaimResult, {
         ok: true;
     }>) => Promise<RemoteCliProof | undefined>;
+    /** #282 S3: the basis for a receipt to a local CLI from a member frozen on this host's own forward, else undefined. */
+    readonly forwardReceiptBasis: (taskId: string, caller: string, cliHandle: string, claim: Extract<OriginClaimResult, {
+        ok: true;
+    }>) => string | 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;
@@ -169,6 +177,7 @@ export interface WireDeps {
     /** 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 waitForForwardBirth: (message: string) => Promise<void>;
     readonly settleAndAnnounce: (message: string, settler?: Settler) => SettlementRefusal | undefined;
     readonly touchWakeDemand: () => void;
     readonly session: string;
@@ -199,7 +208,7 @@ export interface WireDeps {
     readonly nativeTeamsRound: (prepared: Extract<NativePrepared, {
         ok: true;
     }>, team: string, caller: string, message: string, taskId: string | undefined, proofClause: string, external?: AbortSignal, proofHeader?: (team: string, taskId: string, from: string, proofClause: string) => string) => Promise<NativeRoundOutcome>;
-    readonly routeIntoAgent: (team: string, message: string, caller: string, taskId?: string, proofClause?: string, directHeader?: (from: string) => string) => Promise<RouteOutcome>;
+    readonly routeIntoAgent: (team: string, message: string, caller: string, taskId?: string, proofClause?: string, directHeader?: (from: string) => string, localFrom?: string, onSteered?: (target: Agent, floor: number) => void) => Promise<RouteOutcome>;
 }
 /**
  * #187: what a verified claim may vouch for at settlement. The signing key always (the card was

package/lib/types/index.d.ts

@@ -20,9 +20,7 @@ export declare function resolveCallerLabel(input: {
 }): string | undefined;
 import { type ReceiptResolvedInfo } from './task-ledger.ts';
 import { type AffectedEntry } from './auth-observer.ts';
-import { type SettlementMode } from './task-auth.ts';
 import type { Context } from '@deepseek-ai/cordis';
-import s from '@deepseek-ai/schemastery';
 declare module '@deepseek-ai/dsh-llm' {
     interface MessageSourceMap {
         'a2a-relay': {
@@ -50,281 +48,9 @@ declare module '@deepseek-ai/cordis' {
 }
 export declare const name = "a2a";
 export declare const inject: string[];
-/** One signed zone delegation published on this node's agent card. */
-export interface DelegateConfig {
-    /** The delegated name; resolves zone-relatively at route time. */
-    readonly name: string;
-    /** Base URL of the zone the name resolves in. */
-    readonly url: string;
-    /** Base64 SPKI DER binding to the target zone's card key; `''` leaves the delegation unbound. */
-    readonly publicKey: string;
-}
-/** Deployment-varying A2A node facts; every field has a declared default. */
-export interface Config {
-    /** `X-API-Key` value sent on peer requests and required by the control routes; empty disables the header. */
-    readonly apiKey: string;
-    /**
-     * This node's caller label. `''` (the default) derives `dsh-host-<8 hex>`
-     * from a per-home node id created on first use, so two deployments mounting
-     * defaults do not collide while a persisted home keeps the label stable
-     * across restarts.
-     */
-    readonly session: string;
-    /** Team name this node exposes for direct routing. */
-    readonly team: string;
-    /** S4 fix 3: audit (default) or refuse host-side (agent-less) routing calls. */
-    readonly gateAgentLessCalls: 'audit' | 'refuse';
-    /** #114 S4: settlement authorization — off, observe (record would-refuse, settle as before), enforce. */
-    readonly settlementAuth: SettlementMode;
-    /**
-     * Publish this node's `/.well-known/agent-card.json` on the shared web
-     * server (peer discovery). Requires the web server in the composition;
-     * the card carries this node's team, capabilities, referral list, and
-     * joined session teams so peers find it without a central directory.
-     */
-    readonly announce: boolean;
-    /**
-     * gh#193: send nothing to any peer. Every outbound peer request — card
-     * reads, directory sweeps, routes, log reads, canvas pings and canvas-op
-     * relays — goes through one fetch that refuses while this is on, so a
-     * test host stays dark even with learned peers in `a2a/peers.json`
-     * (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;
-    /**
-     * Base URLs of seed peer nodes. `a2a_teams` lists teams discovered from
-     * the peers' agent cards and `a2a_route` connects to the owning peer's
-     * `/a2a/direct` endpoint. The list is a seed set: referral URLs learned
-     * from fetched cards join a bounded, quality-scored peer store persisted
-     * at `<dsh-home>/a2a/peers.json`.
-     */
-    readonly peers: string[];
-    /**
-     * Zone delegation records published (signed) on this node's agent card:
-     * each entry publishes `name` as resolvable in the zone at `url`, so a
-     * route for `name` walks the delegation chain (at most 5 hops, cycles
-     * fail closed).
-     */
-    readonly delegates: DelegateConfig[];
-    /**
-     * gh#9+gh#10 OriginClaim window (docs/protocol/delivery-origin-auth.md §4):
-     * while true (default), a delivery/log request with NO envelope still
-     * walks N3 admission and increments the legacyInbound warn metric; when
-     * the operator closes it (post fleet flip), an absent envelope rejects
-     * `untrusted-origin` — same code as a failed signature (M1: a
-     * self-asserted already-linked name must not pass on shape alone).
-     */
-    readonly originClaimWindow: boolean;
-    /**
-     * OriginClaim unbound window (docs/protocol/delivery-origin-auth.md §2.1):
-     * while true (default), this host also signs the legacy unbound form and
-     * accepts a peer's unbound-only envelope (counted as unboundInbound);
-     * closed, it signs and accepts the audience-bound form only.
-     */
-    readonly originClaimUnboundWindow: boolean;
-    /**
-     * Extra origins this host answers to as an OriginClaim audience, beyond
-     * its card URL and the address a request arrives on (port-mapped or
-     * proxied hosts name the URL peers dial).
-     */
-    readonly originClaimAudiences: string[];
-    /**
-     * #19 D2: card-face sessionTeams excerpt exposure — 'full' | 'masked'
-     * | 'off' (owner-level; default full). See the schema comment.
-     */
-    readonly exposureExcerpt: 'full' | 'masked' | 'off';
-    /**
-     * Override for the OriginClaim callerUrl anchor. Loopback-bound hosts
-     * behind a pocket tunnel must name the card URL peers can actually
-     * fetch (e.g. http://192.168.3.157:13080); empty uses the web server's
-     * own address.
-     */
-    readonly originClaimUrl: string;
-    /**
-     * gh#8 (N9) escape hatch: when true, team-name resolution also considers
-     * the referral-learned peer tail (the legacy whole-store basis) instead
-     * of the seeded/delegate subset only. Default false — a team name binds
-     * to hosts the operator linked; fleets relying on referral discovery for
-     * routing migrate by adding explicit seeds, then leave this off.
-     */
-    readonly referralTeamResolution: boolean;
-    /**
-     * Harness home slice for the node keypair and peer store; `''` (the
-     * default) uses the process DSH home. The Ed25519 key lives at
-     * `<home>/a2a/node-key.pem` and is generated on first announce; a
-     * persisted key keeps the node's card identity stable across restarts.
-     */
-    readonly dshHome: string;
-    /**
-     * Agent-card validity. Announce re-signs at TTL/4 so three lost refreshes
-     * still leave a live card; a node silent for one TTL disappears from every
-     * peer's discovery without manual eviction.
-     */
-    readonly cardTtlMs: number;
-    /**
-     * Enable per-session A2A nodes: each live top-level session can join the
-     * network explicitly — label `<session>-<agentId8>`, team
-     * `<team>/<agentId8>`, node facts carrying the session title and a
-     * recent-activity excerpt. Joining is opt-in through the sidebar control's
-     * host routes; joined teams ride this node's card and dispatch through
-     * its `/a2a/direct` endpoint.
-     */
-    readonly sessionNodes: boolean;
-    /**
-     * Prewarm every cold joined session's agent after the plugin mounts (dev
-     * boxes and always-on collaboration hosts that restart often: the network
-     * state returns without opening each session). Each wake materializes a
-     * full agent — a main-thread log replay — so the prewarm is deferred,
-     * foreground-yielding, and cancellable (see `wakePrewarmDelayMs` /
-     * `wakePrewarmQuietMs`); the default stays off for deployments that would
-     * rather pay on demand (wake-on-route and the sidebar's wake button remain
-     * available either way).
-     */
-    readonly wakeJoinedOnBoot: boolean;
-    /**
-     * Idle delay between loader settlement and the first boot prewarm wake:
-     * boot traffic gets a clear window before any log replay starts. `0`
-     * restores the old fire-at-settle behavior.
-     */
-    readonly wakePrewarmDelayMs: number;
-    /**
-     * Foreground quiet window: a wake/route demand inside this window (or any
-     * outbound route still in flight) postpones the next prewarm step. Panel
-     * polls never count. `0` disables the yield.
-     */
-    readonly wakePrewarmQuietMs: number;
-    /**
-     * Pause between consecutive boot prewarm wakes. Each wake replays a full
-     * session log — the zstd decode yields the event loop only every 500ms —
-     * so unbounded concurrent wakes of several huge logs starve every request
-     * for tens of seconds after a restart. The serial queue with this pause
-     * keeps the preheat while capping decode saturation, and wake-on-route
-     * never waits on this queue.
-     */
-    readonly wakeBootStaggerMs: number;
-    /**
-     * F8: continuous desired-state reconciliation. The boot prewarm is a
-     * one-shot queue; the reconciler re-derives the due set every tick and
-     * wakes one cold intent per pass — covering post-boot drift, failed
-     * wakes, and gateways that mounted late. Default on.
-     */
-    readonly wakeReconcile: boolean;
-    /** Cadence between reconciliation ticks (floored at 50ms). */
-    readonly wakeReconcileIntervalMs: number;
-    /** First-retry delay after a failed reconcile wake; doubles per attempt. */
-    readonly wakeReconcileBackoffBaseMs: number;
-    /** Backoff ceiling; corrupt-log rows park as needs-repair and never retry. */
-    readonly wakeReconcileMaxBackoffMs: number;
-    /**
-     * S4 (gh#11 N7, operator directive: team creation is a human act): the
-     * joinable-team curation list for a2a_team_join. ONLY an EXACT entry
-     * authorizes a join; trailing-`*` pattern entries stay readable here
-     * (whoami shows them) but carry no mint rights — a pattern that
-     * pre-authorized every future name under it would let a model mint teams
-     * nobody created. Empty list denies every join (default).
-     */
-    readonly teamJoinAllowlist: string[];
-    /** Human-owned stable display labels keyed by full local session id; never a routing identity. */
-    readonly seatNames: Record<string, unknown>;
-    /**
-     * S3 (phase-2 default-ON, owner ruling 2026-09-01): route dispatch checks
-     * caller↔target shared team membership before addressing; set false to
-     * restore the open outbound seam. (Kept in sync with the schema comment.)
-     */
-    readonly teamScopeRouting: boolean;
-    /**
-     * S5 (owner directive 2026-10-20): information-plane scoping — the
-     * read-only fleet tools (a2a_teams / a2a_status / a2a_probe) disclose
-     * only teams joined by this host's nodes (the union of local roster
-     * declarations). [this host] rows stay visible; a2a_tasks (this host's
-     * own ledger) stays unscoped. Set false for the open plane.
-     */
-    readonly teamScopeInfo: boolean;
-    /**
-     * Peer boundary model (docs/design/peer-boundary-model.md) — 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.
-     */
-    readonly peerAllowlist: string[];
-    /**
-     * 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.
-     */
-    readonly referralLearning: boolean;
-    /**
-     * 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
-     * default keeps one full enumeration per 5s instead of one per poll.
-     */
-    readonly stateColdRowsTtlMs: number;
-    /**
-     * Serve window for a verified peer card from the shared cache. Cards are
-     * signed for days and re-signed at TTL/4, so 60s is semantically safe; a
-     * peer that restarts with a fresh card is picked up on the next window.
-     */
-    readonly cardCacheTtlMs: number;
-    /** Shorter window for unreachable/invalid cards, so a revived peer reappears quickly. */
-    readonly cardCacheNegativeTtlMs: number;
-    /**
-     * Serve window for the panel\x27s remote rows. The refresh itself rides the
-     * shared card cache, so this is pure sweep cadence: how often real
-     * network activity happens while the panel polls every 2s.
-     */
-    readonly remoteRowsTtlMs: number;
-    /**
-     * `final` reply budget: how long an inbound direct route waits for the
-     * session's next assistant message before answering with a timeout
-     * notice. Without it a session that never idles (or never produces text)
-     * leaves the caller hanging until `routeTimeoutMs` expires.
-     */
-    readonly flushTimeoutMs: number;
-    /**
-     * `a2a_route` execution budget: how long a call may plausibly wait for a
-     * remote session's reply (default 30 minutes).
-     */
-    readonly routeTimeoutMs: number;
-    /**
-     * Age at which an unsettled async task auto-dead-letters (exits the owed
-     * view, disarms the nudge, still settles on a late receipt). Default
-     * 24h; the mesh anomaly suite injects sub-second windows to exercise the
-     * dead-letter → revival lifecycle without wall-clock waits.
-     */
-    readonly taskStaleTtlMs: number;
-    /**
-     * Opt-in native-teams inbound bridge: when composed with
-     * `@nelsonlongxiang/dsh-native-teams`, a routed team name that its
-     * registry classifies as an unambiguous local claim dispatches through
-     * its authoritative routing seam (`/a2a/direct`, the outbound A2A tools,
-     * and the directory listing). Off by default — exposing every registered
-     * team to the network is an operator decision (exposure-grants
-     * governance: grants are deliberate, never ambient). Dispatcher-level
-     * only: inbound callers address the team, never its individual members
-     * (members stay visible-not-addressable).
-     */
-    readonly nativeTeamsInbound?: boolean;
-    /**
-     * Reply-wait budget for one native-teams round (the bridge's answer
-     * deadline, mirroring the steer path's 180s deadline). A round still
-     * running past it answers the honest delivered-unsettled shape instead
-     * of parking the caller; the round itself keeps going.
-     */
-    readonly nativeRoundWaitMs?: number;
-}
-/** Schemastery configuration for the A2A client plugin row. */
-export declare const Config: s<Config>;
+import { Config } from './config.ts';
+export { Config };
+export type { DelegateConfig } from './config.ts';
 /**
  * Register the outbound peer tools, the direct-route endpoint, and (when
  * composed) the announced card and session-node control surface.

package/lib/types/live-roots.d.ts

@@ -0,0 +1,35 @@
+/**
+ * #291: live top-level agents across harness generations.
+ *
+ * Hosts up to 0.2.1 expose `AgentRegistry.roots()` — "all live top-level
+ * agents (created without an owning agent context)". 0.2.2-rc removed it:
+ * live lineage moved to the subagent tree and the registry keeps only
+ * `list()` (all live agents). Top-level is then the delegation-depth
+ * predicate of `@deepseek-ai/dsh-subagent/depth` `delegationDepthOf` —
+ * depth 0 is top-level, absence is top-level. That package is not a
+ * plugin-provided dependency, so its read is mirrored here.
+ *
+ * Nothing in this module throws. The `agent/created` listener runs at
+ * session publication and a throwing listener vetoes the publication — the
+ * 2026-11-05 session-resume incident (history sessions vanished from the
+ * list until refresh). An unreadable or throwing registry surface degrades
+ * to an empty join surface, never to a broken session list. Unlike the
+ * harness' own `delegationDepthOf`, invalid depth values read as absent
+ * instead of throwing, for the same reason.
+ */
+import type { Agent, AgentRegistry } from '@deepseek-ai/dsh-agent';
+/**
+ * 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 declare function delegationDepthOf(agent: Agent): number;
+/** Whether a live agent is top-level (not inside any subagent tree). */
+export declare function isTopLevelAgent(agent: Agent): boolean;
+/**
+ * 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 declare function liveRootAgents(registry: AgentRegistry | undefined | null): Agent[];

package/lib/types/origin-claim.d.ts

@@ -56,6 +56,7 @@ export type OriginClaimVerdict = {
     card: A2aPeerCard;
     bound: boolean;
     cli?: true;
+    bodyBound?: true;
 } | {
     ok: false;
     reason: OriginClaimRefusal;
@@ -117,7 +118,10 @@ export declare function verifyOriginClaim(req: IncomingMessage, d: {
     /** Count one accepted unbound envelope (the drain gauge). */
     readonly onUnbound: () => void;
     /** Count one bound form that missed and fell back to the unbound one. */
-    readonly onBoundMiss?: () => void;
+    readonly onBoundMiss?: (miss: {
+        readonly caller: string;
+        readonly audience: string;
+    }) => void;
     /** A loopback arrival is an audience of its own (default); off when originClaimUrl declares a tunnel or proxy. */
     readonly loopbackArrival?: boolean;
     readonly now: number;

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

@@ -29,5 +29,7 @@ export interface QueueRow {
 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;
+/** #282 S1: the one next step for a full target queue. */
+export declare 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 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/task-auth.d.ts

@@ -17,9 +17,12 @@ export type Admission = {
 } | {
     readonly ok: false;
     readonly refusal: string;
+    readonly next?: string;
 };
 /** The refusal text of a decision, or undefined when admitted — the shape the faces have always read. */
 export declare const refusalOf: (admission: Admission) => string | undefined;
+/** The next step of a refused decision, or undefined. */
+export declare const nextOf: (a: Admission) => string | undefined;
 /** One cached peer card's published canvas org (gh#71). */
 export interface PeerOrgEntry {
     readonly team?: unknown;
@@ -232,6 +235,8 @@ export interface SettlementRow {
     readonly peerHost?: string;
     /** #139: the member that actually received the task (canvas and bare-zone deliveries). */
     readonly deliveredTo?: string;
+    readonly forwarded?: true;
+    readonly receiverMembers?: readonly string[];
 }
 /** Facts from outside the row. */
 export interface SettlementFacts {

package/lib/types/task-ledger-rows.d.ts

@@ -96,31 +96,36 @@ export declare function withAuth(raw: unknown, entry: {
     direction?: unknown;
     team?: unknown;
     peer?: unknown;
+    forwarded?: unknown;
+    sender?: unknown;
 }, now: number): {
     auth?: TaskAuthorization;
 };
 /** Routing and answer facts copied unchanged between a row and its archive entry. */
-export declare function routingOf(row: Pick<TaskRecord, 'peerKey' | 'peerHost' | 'deliveredTo' | 'forwarded' | 'answeredAt'>): Pick<TaskRecord, 'peerKey' | 'peerHost' | 'deliveredTo' | 'forwarded' | 'answeredAt'>;
+export declare function routingOf(row: Pick<TaskRecord, 'peerKey' | 'peerHost' | 'deliveredTo' | 'forwarded' | 'answeredAt' | 'receiverMembers'>): Pick<TaskRecord, 'peerKey' | 'peerHost' | 'deliveredTo' | 'forwarded' | 'answeredAt' | 'receiverMembers'>;
 /** #139: what an outbound row is born with besides its sender. */
 export interface OutboundBirth {
     readonly forwarded?: true;
-    /** The local-candidate admission (ingress local); kept only on a row whose peer is 'local'. */
+    /** Local-candidate admission, or a forwarded online CLI's verified wire admission. */
     readonly auth?: TaskAuthorization;
     readonly peerKey?: string;
     readonly peerHost?: string;
     readonly deliveredTo?: string;
+    /** Verified selected peer canvas membership at dispatch; actual deliveredTo remains stricter when available. */
+    readonly receiverMembers?: readonly string[];
 }
 /** The facts of one outbound birth that fit the row (see {@link withRouting} for the same shape on restore). */
-export declare function birthFacts(peer: string, birth: OutboundBirth | undefined): Pick<TaskRecord, 'auth' | 'peerKey' | 'peerHost' | 'deliveredTo' | 'forwarded'>;
+export declare function birthFacts(peer: string, birth: OutboundBirth | undefined, team?: string, sender?: Sender, now?: number, warn?: (message: string) => void): Pick<TaskRecord, 'auth' | 'peerKey' | 'peerHost' | 'deliveredTo' | 'forwarded' | 'receiverMembers'>;
 /** Bound on a persisted routing fact; anything longer (or empty, or not a string) is dropped on restore. */
 export declare const ROUTING_FACT_CAP = 256;
+export declare function parseReceiverMembers(value: unknown, warn?: (message: string) => void): readonly string[] | undefined;
 /**
  * #139: restore-side allowlist for the routing facts. Each is kept only in
  * its shape — a non-empty string within the cap — and the peer facts only on
  * a remote outbound row; anything else is dropped (the row survives as one
  * born before the fields, judged by current membership and origin).
  */
-export declare function withRouting(entry: Record<string, unknown>): Pick<TaskRecord, 'peerKey' | 'peerHost' | 'deliveredTo' | 'forwarded' | 'answeredAt'>;
+export declare function withRouting(entry: Record<string, unknown>, warn?: (message: string) => void): Pick<TaskRecord, 'peerKey' | 'peerHost' | 'deliveredTo' | 'forwarded' | 'answeredAt' | 'receiverMembers'>;
 /** One tracked outbound task still in the owed book (unsettled). */
 export interface TaskRecord {
     readonly taskId: string;
@@ -164,6 +169,8 @@ export interface TaskRecord {
     readonly peerHost?: string;
     /** #139: the member that actually received the task (canvas / bare-zone deliveries). */
     readonly deliveredTo?: string;
+    /** Verified selected peer canvas membership at dispatch; actual deliveredTo remains stricter when available. */
+    readonly receiverMembers?: readonly string[];
     /** Local target has produced an answer; still owed until receipt delivery/settlement, but no longer queued. */
     answeredAt?: number;
     status: TaskStatus;
@@ -221,6 +228,8 @@ export interface ArchivedRecord {
     readonly peerKey?: string;
     readonly peerHost?: string;
     readonly deliveredTo?: string;
+    /** Verified selected peer canvas membership at dispatch; actual deliveredTo remains stricter when available. */
+    readonly receiverMembers?: readonly string[];
     /** Local answer time retained as audit metadata, independent of resolution time. */
     readonly answeredAt?: number;
     /** #114 S4: who settled the row (receipt and echo ends), and their chain role. */
@@ -252,6 +261,8 @@ export interface CancelledResult extends AbandonResult {
 }
 /** Per-instance knobs; defaults come from the exported constants. */
 export interface TaskLedgerOptions {
+    /** Invalid persisted member entries are dropped individually and reported without their content. */
+    warn?: (message: string) => void;
     /** Stale-TTL override (tests inject short windows); defaults to {@link TASK_STALE_TTL_MS}. */
     staleTtlMs?: number;
     /** Archive capacity override; defaults to {@link ARCHIVE_CAP}. */
@@ -331,7 +342,7 @@ export declare const SETTLEMENT_REFUSAL_CAP = 64;
 export interface SettlementJudge {
     readonly enforce: boolean;
     readonly settler: SettlementRefusalRecord['settler'];
-    check(row: Pick<TaskRecord, 'team' | 'peer' | 'direction' | 'auth' | 'peerKey' | 'peerHost' | 'deliveredTo'>, echo: boolean): SettlementVerdict;
+    check(row: Pick<TaskRecord, 'team' | 'peer' | 'direction' | 'auth' | 'peerKey' | 'peerHost' | 'deliveredTo' | 'forwarded' | 'receiverMembers'>, echo: boolean): SettlementVerdict;
 }
 /** Restore-side allowlist for settledBy: whole or nothing. */
 export declare function withSettledBy(raw: unknown): {

package/lib/types/task-ledger.d.ts

@@ -44,6 +44,7 @@ export declare class TaskLedger {
     private readonly archiveCap;
     /** Injectable clock (option `now`). */
     private readonly now;
+    private readonly warn;
     /**
      * @param path - persistence file (`<dsh-home>/a2a/tasks.json`); empty = no persistence.
      * @param options - TTL/capacity overrides; defaults come from the exported constants.
@@ -55,6 +56,8 @@ export declare class TaskLedger {
      * @returns the owed-book records.
      */
     list(): readonly TaskRecord[];
+    /** #275: old forwarded canvas debts cannot be safely upgraded by inventing receiver authority. */
+    settlementEnforceBlockers(): string[];
     /**
      * The settled archive, most recently resolved first. Rows land here the
      * moment their receipt correlates and stay until the archive cap evicts

package/lib/types/tools/info.d.ts

@@ -18,6 +18,9 @@ export type DirectoryTeamRow = {
     session: string;
     name: string;
     seatName?: string;
+    kind?: 'canvas';
+    owner?: string;
+    memberCount?: number;
     description: string;
     local?: boolean;
     origin?: string;

package/lib/types/types.d.ts

@@ -160,6 +160,8 @@ export interface A2aRouteError {
     /** A2A JSON-RPC-style code when the peer supplied one. */
     readonly code?: number;
     readonly task_id?: string;
+    /** One actionable next step for the caller (#282 S1); absent when nothing the caller can do helps. */
+    readonly next?: string;
 }
 /** Canonical `a2a_route` value: success or explicit failure. */
 export type A2aRouteResult = A2aRouteOk | A2aRouteError;