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

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

@@ -13,6 +13,8 @@ export type A2aSchedule = (callback: () => void, delayMs: number) => () => void;
 export type A2aFetch = (url: string, init: {
     readonly method: 'GET' | 'POST';
     readonly headers: Record<string, string>;
+    /** Optional fetch redirect policy; origin verification sets manual. */
+    readonly redirect?: 'follow' | 'error' | 'manual';
     readonly body?: string;
     readonly signal?: AbortSignal;
 }) => Promise<{
@@ -35,11 +37,15 @@ export interface A2aClientOptions {
     readonly cardCaller: string;
     /**
      * gh#9+gh#10 OriginClaim signer (docs/protocol/delivery-origin-auth.md):
-     * produces the four envelope headers with the NODE'S CARD KEY. Present ⇒
-     * every card GET and direct POST carries a verifiable origin claim;
-     * absent ⇒ the caller stays at the named-only posture (transition).
+     * produces the envelope headers with the NODE'S CARD KEY, bound to the
+     * request's target URL and method. Present ⇒ every card GET and direct
+     * POST carries a verifiable origin claim; absent ⇒ the caller stays at
+     * the named-only posture (transition).
      */
-    readonly originClaim?: () => Record<string, string>;
+    readonly originClaim?: (target: {
+        readonly url: string;
+        readonly method: string;
+    }) => Record<string, string>;
     /** Delayed-callback seam (HTTP timeouts). */
     readonly schedule: A2aSchedule;
     /** HTTP seam. */

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

@@ -0,0 +1,110 @@
+import type { Admission, TaskAuthorization } from './task-auth.ts';
+/** Ring size of both the version history and the affected-task entries. */
+export declare const AUTH_HISTORY_CAP = 32;
+/** Longest refusal text kept on an affected task (the faces' texts fit; a longer one is cut, flagged by `…`). */
+export declare const AFFECTED_REASON_CAP = 400;
+/** One recorded allowlist version and what it hashed. */
+export interface AuthVersionEntry {
+    readonly version: string;
+    readonly at: number;
+    /** Why it was observed: `boot`, `joined`, `canvas`, `roster`, or `lazy` (a read noticed a change no hook reported — CLI expiry, config). */
+    readonly cause: string;
+    /** The canonical inputs (task-auth.ts canonicalAllowlist), parsed. */
+    readonly inputs: unknown;
+}
+/**
+ * One task's re-judgement. `basis-changed`: still admitted, but on teams that
+ * no longer overlap the record's; `would-revoke`: today's records refuse the
+ * caller — `reason` is that refusal text.
+ */
+export interface AffectedTask {
+    readonly taskId: string;
+    readonly direction: 'inbound' | 'outbound';
+    readonly caller: string;
+    readonly target: string;
+    readonly verdict: 'basis-changed' | 'would-revoke';
+    readonly reason: string;
+}
+/** One observation that found affected tasks. */
+export interface AffectedEntry {
+    readonly at: number;
+    /** The previously recorded version; null when there was no history yet. */
+    readonly from_version: string | null;
+    readonly to_version: string;
+    readonly cause: string;
+    readonly tasks: readonly AffectedTask[];
+}
+/** The minimum of a ledger row the judgement reads. */
+export interface JudgedRow {
+    readonly taskId: string;
+    readonly direction?: 'inbound' | 'outbound';
+    readonly auth?: TaskAuthorization;
+}
+/**
+ * Re-judge rows against today's records — pure: `judge` must be a read-only
+ * admission decision (task-auth.ts callerAdmission over the live records).
+ * A row is judged when it carries a record and either was born under another
+ * version than `version` or `cacheResting(row)` says its admission rests on
+ * the peer-card cache (`peer-org`, which the version does not hash; by
+ * 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[];
+/** What one {@link AuthObserver.observe} call needs from the host. */
+export interface ObserveInput {
+    readonly version: string;
+    /** The canonical inputs the version hashed (recorded with a new version). */
+    readonly inputs: () => unknown;
+    readonly cause: string;
+    readonly rows: () => readonly JudgedRow[];
+    readonly judge: (caller: string, target: string, ingress: 'wire' | 'local') => Admission;
+}
+/**
+ * The persisted observer. One instance per host; every entry point is
+ * total and never throws (an unwritable home degrades to memory-only).
+ */
+export declare class AuthObserver {
+    private readonly path;
+    private readonly now;
+    private versions;
+    private affected;
+    /**
+     * The last report per task ({@link reportKey}), so a task still affected
+     * the same way is not listed again — on a peer-org recheck poll, nor on a
+     * later unrelated version move. A task judged unaffected is forgotten, so
+     * a relapse reports again; a task gone from the rows is pruned.
+     * Boot-local by design: after a restart the next version change reports
+     * afresh.
+     */
+    private readonly reported;
+    /**
+     * The rule of each task's latest passing judgement. Whether a row rests on
+     * the peer-card cache is read from here first, the birth record second: a
+     * row born remote-ref-samezone that today passes only through `peer-org`
+     * is rechecked like one born there (and stops being once a firm rule
+     * admits it again).
+     */
+    private readonly lastRule;
+    constructor(path: string, now?: () => number);
+    /** The version history, newest first. */
+    history(): readonly AuthVersionEntry[];
+    /** The affected-task entries, newest first. */
+    entries(): readonly AffectedEntry[];
+    /**
+     * Record the current version when it moved, and re-judge.
+     * - Version moved: append it to the history; judge every row born under
+     *   another version and every cache-resting row.
+     * - Version unchanged: only cache-resting rows are re-judged.
+     * - Cause `boot`: cache-resting rows are not judged at all — the peer-card
+     *   cache is empty at boot, so every one of them would read as refused.
+     *   The first read after boot (`lazy`) rechecks them.
+     * Either way a task is reported only when its report differs from the
+     * last one for it ({@link reportKey}).
+     * @returns the new affected entry, or undefined when nothing was affected.
+     */
+    observe(input: ObserveInput): AffectedEntry | undefined;
+    /** Forget the per-task memory of tasks no longer among the unsettled rows. */
+    private prune;
+    private restore;
+    private persist;
+}

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

@@ -0,0 +1,83 @@
+/** One file's ceiling, in bytes (64 MiB; design §8). */
+export declare const BLOB_FILE_MAX: number;
+/** The store's ceiling, in bytes (1 GiB). */
+export declare const BLOB_TOTAL_MAX: number;
+/** The store's ceiling, in blobs. */
+export declare const BLOB_COUNT_MAX = 256;
+/** How long a grant lets its target pull (24h). */
+export declare const BLOB_GRANT_TTL_MS: number;
+/** A sanitized file name's length cap. */
+export declare const BLOB_NAME_MAX = 120;
+/** One grant: `to` may pull `sha256` until `expiresAt`. */
+export interface BlobGrant {
+    readonly sha256: string;
+    readonly size: number;
+    readonly name: string;
+    /** The target team or handle, exactly as the sender routed to it. */
+    readonly to: string;
+    /** The staging session (or CLI handle). */
+    readonly by: string;
+    readonly grantedAt: number;
+    readonly expiresAt: number;
+}
+export type StageResult = {
+    readonly ok: true;
+    readonly sha256: string;
+    readonly size: number;
+    readonly name: string;
+    readonly expiresAt: number;
+} | {
+    readonly ok: false;
+    readonly code: 'bad-request' | 'too-large' | 'full';
+    readonly error: string;
+};
+/** A file name that can only land inside the inbox: no path, no `..`, no control characters, bounded. */
+export declare function sanitizeBlobName(name: string): string;
+/** The one-line reference a session message carries (design §3.1). */
+export declare function formatFileRef(ref: {
+    sha256: string;
+    size: number;
+    name: string;
+    from: string;
+}): string;
+/** Parse a reference line (anywhere in a message); undefined when it is not a well-formed v1 reference. */
+export declare function parseFileRef(text: string): {
+    sha256: string;
+    size: number;
+    name: string;
+    from: string;
+} | undefined;
+export declare class BlobStore {
+    private readonly root;
+    private readonly now;
+    private grants;
+    /**
+     * @param root - the store's directory (`<home>/a2a`); '' = in-memory grants and no blob files (tests of the grant logic only).
+     * @param now - clock (tests).
+     */
+    constructor(root: string, now?: () => number);
+    private get grantsFile();
+    private blobPath;
+    /** Stage bytes for `to`; a repeat of the same (sha256, to) only extends the grant. */
+    stage(bytes: Uint8Array, meta: {
+        name: string;
+        to: string;
+        by: string;
+    }): StageResult;
+    /**
+     * The live grant that lets one of `callerTeams` pull `sha256`, if any. `callerTeams` are the
+     * teams the WIRE FACE proved for the caller (OriginClaim + membership) — never self-described.
+     */
+    grantFor(sha256: string, callerTeams: readonly string[]): BlobGrant | undefined;
+    /** The bytes of a granted blob (undefined when the file is gone or does not hash back). */
+    read(grant: BlobGrant): Uint8Array | undefined;
+    /** Live grants (for the state face). */
+    list(): readonly BlobGrant[];
+    private hasBlob;
+    /** Blobs some live grant still names, with their sizes. */
+    private liveBlobs;
+    /** Drop expired grants and every blob file no live grant names. */
+    private sweep;
+    private persist;
+    private restore;
+}

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

@@ -29,11 +29,42 @@ export interface CliMail {
     readonly at: number;
     readonly from: string;
     readonly text: string;
+    /**
+     * gh#113: the entry's place in its handle's mailbox — 1, 2, 3, … in
+     * arrival order, never reused, kept across restarts. A reader that keeps
+     * the last seq it read sees exactly what is new, and any gap below
+     * `oldest_seq` is mail the cap pushed out before it was read.
+     */
+    readonly seq: number;
+    /** gh#113: set when `text` was cut to MAILBOX_TEXT_CAP; `chars` is the original length. */
+    readonly truncated?: true;
+    readonly chars?: number;
 }
+/** gh#113: one mailbox read — the rows plus what a reader needs to notice loss. */
+export interface CliMailbox {
+    /** Newest first, as before gh#113. */
+    readonly mail: readonly CliMail[];
+    /** Changes when the store starts empty (no snapshot, or a corrupt one): seq restarted at 1. */
+    readonly epoch: string;
+    /** The seq the next delivery will get; `next_seq - 1` is the newest ever written. */
+    readonly next_seq: number;
+    /** The oldest seq still held, or `next_seq` when the mailbox is empty. */
+    readonly oldest_seq: number;
+    /** Entries the cap pushed out for this handle, all time. */
+    readonly dropped: number;
+}
+export declare const MAILBOX_CAP = 64;
+export declare const MAILBOX_TEXT_CAP = 4000;
 export declare class CliDepositStore {
     private readonly path;
     private deposits;
     private mailbox;
+    private nextSeq;
+    private dropped;
+    private truncated;
+    private epoch;
+    /** gh#113 review: true while the last write failed — the epoch on disk no longer matches memory. */
+    private unpersisted;
     private now;
     constructor(path: string, options?: {
         now?: () => number;
@@ -72,6 +103,13 @@ export declare class CliDepositStore {
     }>;
     mail(handle: string, from: string, text: string): void;
     readMail(handle: string): readonly CliMail[];
+    /** gh#113: the mailbox with its seq bounds and loss counter; `afterSeq` keeps only newer rows. */
+    readMailbox(handle: string, afterSeq?: number): CliMailbox;
+    /** gh#113: fleet-wide loss counters for the state face (the team verifier reads them). */
+    mailStats(): {
+        dropped: number;
+        truncated: number;
+    };
     private sweep;
     /** Mark one row expired (tombstone) and persist. */
     private markExpired;

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

@@ -15,6 +15,7 @@ import type { LayoutStore } from '../layout-store.ts';
 import type { PeerStore } from '../peer-store.ts';
 import { type TaskLedger } from '../task-ledger.ts';
 import type { TeamMembershipStore } from '../team-store.ts';
+import type { OriginClaimTarget } from '../origin-claim.ts';
 /** Remote-team rows cached for the state face (see refreshRemoteRows). */
 export type RemoteRowsCache = {
     at: number;
@@ -25,11 +26,12 @@ export type RemoteRowsCache = {
         via?: string;
         workspace?: string;
         legacy?: boolean;
+        unreachable?: boolean;
         teams?: readonly string[];
     }[];
 } | undefined;
 /** Everything the admin faces used to capture from `apply()`. */
-export interface AdminFaceDeps extends Pick<CanvasNotifyDeps, 'verifyOriginClaim' | 'callerLinkedToThisHost' | 'cachedCardFetch'> {
+export interface AdminFaceDeps extends Pick<CanvasNotifyDeps, 'verifyOriginClaim' | 'callerLinkedToThisHost' | 'cachedCardFetch' | 'peerFetch'> {
     readonly ctx: Context;
     readonly config: Config;
     readonly logger: ReturnType<Context['logger']>;
@@ -51,7 +53,7 @@ export interface AdminFaceDeps extends Pick<CanvasNotifyDeps, 'verifyOriginClaim
         link: 'linked' | 'stranger';
         verified: boolean;
     };
-    readonly originClaimHeaders: () => Record<string, string>;
+    readonly originClaimHeaders: (target: OriginClaimTarget) => Record<string, string>;
     readonly refreshRemoteRows: () => void;
     readonly joinedSessions: JoinedSessions;
     readonly exposureStore: ExposureStore;
@@ -61,6 +63,8 @@ export interface AdminFaceDeps extends Pick<CanvasNotifyDeps, 'verifyOriginClaim
     readonly canvasStore: CanvasStore;
     readonly layoutStore: LayoutStore;
     readonly taskLedger: TaskLedger;
+    /** #114 S6: observe (lazily) and return the /state `authorization` block. */
+    readonly authorizationView: () => unknown;
     readonly idempotencyStore: IdempotencyStore;
     readonly inFlightRoutes: Map<number, InFlightRoute>;
     readonly recentActivity: RouteActivityEntry[];
@@ -108,6 +112,12 @@ export interface AdminFaceDeps extends Pick<CanvasNotifyDeps, 'verifyOriginClaim
     readonly id8: (id: string) => string;
     readonly sessionLabelOf: (agent: Agent) => string;
     readonly sessionTeamOf: (agent: Agent) => string;
+    /** gh#131: the `<zone>/<id8>` handle a canvas may hold for this local session, if it reads as this session. */
+    readonly ownCanvasHandleOf: (id: string) => string | undefined;
+    /** gh#131: the local session a remote-shaped member ref reads as, if unambiguous. */
+    readonly localSessionOfHandle: (ref: string) => string | undefined;
+    /** gh#152: the session's canvas teams read through the local lens — a handle-stored membership of this session counts. */
+    readonly canvasTeamsOfSession: (id: string) => string[];
     readonly nodeMetadataOf: (agent: Agent) => {
         name: string;
         description: string;
@@ -120,6 +130,8 @@ export interface AdminFaceDeps extends Pick<CanvasNotifyDeps, 'verifyOriginClaim
     readonly cardCache: Map<string, CardCacheEntry>;
     readonly remoteRowsCache: RemoteRowsCache;
     readonly legacyInboundCount: number;
+    readonly unboundInboundCount: number;
+    readonly boundMissInboundCount: number;
     readonly ownCardUrl: string;
     ownerAllowlist: string[];
     ownerTeamScopeInfo: boolean;

package/lib/types/faces/canvas-notify.d.ts

@@ -31,6 +31,7 @@ import type { A2aPeerCard } from '../types.ts';
 import type { CanvasStore } from '../canvas-store.ts';
 import type { PeerStore } from '../peer-store.ts';
 import type { CardCacheEntry } from '../runtime.ts';
+import type { OriginClaimTarget } from '../origin-claim.ts';
 /** Coalesce a burst of store writes (a drag that adds three members) into one ping. */
 export declare const CANVAS_NOTIFY_DEBOUNCE_MS = 400;
 /** A peer's pings refresh its card at most this often. */
@@ -42,7 +43,7 @@ export interface CanvasNotifyDeps {
     readonly peerStore: PeerStore;
     readonly canvasStore: CanvasStore;
     readonly cardCache: Map<string, CardCacheEntry>;
-    readonly originClaimHeaders: () => Record<string, string>;
+    readonly originClaimHeaders: (target: OriginClaimTarget) => Record<string, string>;
     readonly verifyOriginClaim: (req: IncomingMessage) => Promise<{
         ok: true;
         caller: string;
@@ -54,6 +55,8 @@ export interface CanvasNotifyDeps {
     }>;
     readonly callerLinkedToThisHost: (caller: string, callerUrl: string, callerCard: A2aPeerCard | undefined) => boolean;
     readonly cachedCardFetch: (url: string) => Promise<A2aPeerCard | undefined>;
+    /** gh#193: the host's guarded peer fetch (refuses while isolated). */
+    readonly peerFetch: typeof globalThis.fetch;
 }
 /**
  * Re-read one peer's card now. Each pass pre-stales the entry (the literal

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

@@ -0,0 +1,53 @@
+/**
+ * #91 file channel, slice F1b (docs/design/file-channel.md §3.2, §3.4, §5): the two HTTP faces
+ * over the sender host's {@link BlobStore}.
+ *
+ * - `GET /a2a/blob?sha256=<hex>&caller_session=<label>` — the PULL face. Admission is the same
+ *   reading the delivery face gives `已验证来源`: an OriginClaim that verifies, and for a host the
+ *   audience-bound (v2) form signed from a ROOT card URL whose zone covers `caller_session`; a
+ *   deposited CLI identity proves its own handle. The caller must then match a live grant's `to`:
+ *   the caller's own label, the signer host itself or one of its canvas teams, or a canvas team of
+ *   THIS host the caller itself is a member of ({@link grantAdmits}).
+ *   A refusal never says whether the blob exists. Pulls are rate-limited per proven signer.
+ * - `POST /__dsh_a2a/blob?to=<team>&name=<file>` — the control-gated STAGE face (CLI `file send`,
+ *   design §3.4): raw bytes in, a grant out. No peer can write into the store.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/faces/files
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import type WebServer from '@deepseek-ai/dsh-host-webserver';
+import type { Config } from '../index.ts';
+import { type BlobStore } from '../blob-store.ts';
+import type { CanvasStore } from '../canvas-store.ts';
+import type { OriginClaimResult } from './wire.ts';
+/** Pulls per proven signer (host zone or CLI handle) in a sliding minute (design §8; the FloodGuard figure). */
+export declare const BLOB_PULLS_PER_MINUTE = 16;
+export interface FileFaceDeps {
+    readonly ctx: Context;
+    readonly config: Pick<Config, 'apiKey' | 'team'>;
+    readonly blobStore: BlobStore;
+    readonly canvasStore: Pick<CanvasStore, 'membersOf'>;
+    readonly verifyOriginClaim: (req: IncomingMessage, options?: {
+        readonly cli?: boolean;
+    }) => Promise<OriginClaimResult>;
+    readonly secretEqual: (a: string, b: string) => boolean;
+    readonly controlRoute: (handler: (req: IncomingMessage, res: ServerResponse) => void) => (req: IncomingMessage, res: ServerResponse) => void;
+    readonly recordActivity: (dir: 'in' | 'out', team: string, peer: string, ok: boolean) => void;
+    readonly now?: () => number;
+}
+/**
+ * Whether a grant's target lets this proven caller pull (design §3.2). For a HOST signer: the
+ * caller's own label; the signer host itself (a grant to the whole zone); one of the signer host's
+ * canvas teams (`<signer>/canvas/<name>` — that host answers for its own membership); or a canvas
+ * team of THIS host (`<zone>/canvas/<name>`; another host's same-named team is a different team) of
+ * which the caller ITSELF is a member. A grant to one session is not another session's, even on the
+ * same host (#91 F2: the honest host's tool names the pulling session, so a mistake cannot cross
+ * sessions). A CLI handle is an identity, never a zone (review of PR #208 R1): only its own grant.
+ * `caller` is already proven by `signer`.
+ */
+export declare function grantAdmits(to: string, caller: string, signer: string, zone: string, localCanvasMembers: (name: string) => readonly string[], cli?: boolean): boolean;
+/**
+ * Register the pull face and the stage face on the shared web server.
+ * @param d - the captures listed on {@link FileFaceDeps}.
+ */
+export declare function registerFileFaces(webServer: WebServer, d: FileFaceDeps): void;

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

@@ -0,0 +1,69 @@
+/**
+ * The `/__dsh_a2a/nodes` face (docs/design/node-identity.md, slice N1).
+ *
+ * - GET rides the ordinary control trust (loopback or apiKey): the roster,
+ *   and with `?name=` one node plus its version numbers and current layers.
+ * - POST is an IDENTITY write (create / update / archive / write-core /
+ *   write-mutable / rollback, bind / unbind a session — N2+N3, and track /
+ *   untrack a task pointer — N6, and approve / reject a queued remote
+ *   self-update — N4). §8-2 (owner ruling 2026-11-02): it requires
+ *   the host's apiKey in `X-API-Key` even on loopback — a host with no
+ *   apiKey refuses identity writes outright. No model tool reaches it.
+ *   Same-host shell access can still edit the files; the design says so
+ *   (§7) instead of pretending otherwise.
+ * @module src/faces/nodes
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import type WebServer from '@deepseek-ai/dsh-host-webserver';
+import type { NodeStore } from '../node-store.ts';
+import type { NodeBinder, NodeBindings } from '../node-bind.ts';
+import type { NodeTasks } from '../node-tasks.ts';
+import type { NodeReviewQueue } from '../node-self.ts';
+/** Identity bodies carry layers of up to 3000 CJK characters; the 10 KiB control default is too small. */
+export declare const NODE_BODY_MAX_BYTES = 32000;
+export interface NodeFaceDeps {
+    readonly ctx: Context;
+    readonly logger: {
+        warn: (format: string, ...args: unknown[]) => void;
+    };
+    readonly nodeStore: NodeStore;
+    readonly bindings: NodeBindings;
+    readonly binder: NodeBinder;
+    readonly tasks: NodeTasks;
+    readonly reviews: NodeReviewQueue;
+    readonly apiKey: () => string;
+    readonly secretEqual: (a: string, b: string) => boolean;
+    readonly controlRoute: (handler: (req: IncomingMessage, res: ServerResponse) => void) => (req: IncomingMessage, res: ServerResponse) => void;
+    readonly readJsonBody: (req: IncomingMessage, res: ServerResponse, use: (body: {
+        readonly id?: unknown;
+        readonly name?: unknown;
+        readonly action?: unknown;
+    }) => void, maxBytes?: number) => void;
+}
+/** §8-2: identity writes need the configured apiKey in the header — loopback is not enough, and no key means no identity writes. */
+export declare function identityVerdict(apiKey: string, presented: unknown, secretEqual: (a: string, b: string) => boolean): {
+    ok: true;
+} | {
+    ok: false;
+    status: 401 | 403;
+    error: string;
+};
+/** One POST body → status + payload. Pure: the route below only does I/O and the identity gate. */
+export declare function nodeAction(store: NodeStore, binder: NodeBinder, tasks: NodeTasks, reviews: NodeReviewQueue, raw: unknown): {
+    status: number;
+    payload: Record<string, unknown>;
+};
+/**
+ * GET view: the roster with the bindings (and what each live session froze at mount), or one node
+ * with its version numbers and current layers. `current` only shows a version that passes the shape
+ * and sha checks (`null` otherwise) — the same reading a mount uses.
+ */
+export declare function nodeView(store: NodeStore, bindings: NodeBindings, binder: NodeBinder, tasks: NodeTasks, reviews: NodeReviewQueue, name: string | null, assembled?: ReadonlyMap<string, {
+    core: boolean;
+    mutable: boolean;
+}>): {
+    status: number;
+    payload: Record<string, unknown>;
+};
+export declare function registerNodeFaces(webServer: WebServer, d: NodeFaceDeps): void;

package/lib/types/faces/session-log.d.ts

@@ -0,0 +1,44 @@
+/**
+ * gh#77 (src/index.ts line ratchet): the two session-log faces, moved verbatim out of apply() —
+ * the LOCAL transcript reader `/__dsh_a2a/session-log` and the REMOTE proxy
+ * `/__dsh_a2a/remote-session-log`. Behavior unchanged; apply() hands over the captures below.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/faces/session-log
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import type WebServer from '@deepseek-ai/dsh-host-webserver';
+import type { Config } from '../index.ts';
+import type { PeerStore } from '../peer-store.ts';
+import type { A2aPeerCard } from '../types.ts';
+/** Everything the session-log faces capture from apply(). */
+export interface SessionLogFaceDeps {
+    readonly ctx: Context;
+    readonly config: Pick<Config, 'team'>;
+    readonly controlRoute: (handler: (req: IncomingMessage, res: ServerResponse) => void) => (req: IncomingMessage, res: ServerResponse) => void;
+    readonly scanSessionLogList: () => Array<{
+        id: string;
+        mtimeMs: number;
+        sizeBytes: number;
+    }>;
+    readonly readSessionLogTail: (id: string, limit: number) => {
+        ok: true;
+        id: string;
+        messages: Array<{
+            role: string;
+            text: string;
+            time?: number;
+        }>;
+    } | {
+        ok: false;
+        error: string;
+    };
+    readonly peerStore: Pick<PeerStore, 'list'>;
+    readonly peerFetch: typeof globalThis.fetch;
+    readonly directoryPeerCandidates: (fetch: (url: string) => Promise<A2aPeerCard | undefined>, team: string, failures: string[]) => Promise<string[]>;
+    readonly memoizedCardFetch: () => (url: string) => Promise<A2aPeerCard | undefined>;
+}
+/**
+ * Register the local transcript reader and the remote-log proxy on the shared web server.
+ * @param d - the captures listed on {@link SessionLogFaceDeps}.
+ */
+export declare function registerSessionLogFaces(webServer: WebServer, d: SessionLogFaceDeps): void;

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

@@ -20,7 +20,16 @@ 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 { Config } from '../index.ts';
+/**
+ * #139 (design §4.4): add `settlement: {status:'refused', reason, task_id}`
+ * to whatever JSON object this response ends with. The delivery face has
+ * many exits (mailbox, no-wait, waiting, refusals); deferring the head until
+ * the body is known keeps one rule for all of them. A non-JSON or non-object
+ * body is sent unchanged.
+ */
+export declare function withSettlementField(res: ServerResponse, settlement: SettlementRefusal): void;
 /** The cold-wake answer (mirrors index.ts's local ColdWake). */
 export type ColdWake = {
     readonly kind: 'flight';
@@ -98,6 +107,8 @@ export type OriginClaimResult = {
     caller: string;
     callerUrl: string;
     card: A2aPeerCard;
+    bound: boolean;
+    cli?: true;
 } | {
     ok: false;
     reason: string;
@@ -112,12 +123,22 @@ export interface WireDeps {
     readonly sessionNodes: Map<string, Agent>;
     readonly joinedSessions: JoinedSessions;
     readonly idempotencyStore: IdempotencyStore;
-    readonly verifyOriginClaim: (req: IncomingMessage) => Promise<OriginClaimResult>;
+    readonly verifyOriginClaim: (req: IncomingMessage, options?: {
+        readonly cli?: boolean;
+    }) => Promise<OriginClaimResult>;
     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;
     readonly recordActivity: (dir: 'in' | 'out', team: string, peer: string, ok: boolean) => void;
     readonly bumpLegacyInbound: () => void;
     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;
+    /** #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). */
+    readonly observeAuthorization: (cause: string) => void;
     readonly scanSessionLogList: () => Array<{
         id: string;
         mtimeMs: number;
@@ -137,7 +158,8 @@ export interface WireDeps {
     };
     readonly taskLedger: TaskLedger;
     readonly refuseIfFlooded: (caller: string, message: string, team: string, taskId: string, res: ServerResponse) => boolean;
-    readonly settleAndAnnounce: (message: string) => void;
+    /** 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;
     readonly session: string;
     readonly resolveAgentForTeam: (team: string) => Agent | undefined;
@@ -145,9 +167,16 @@ export interface WireDeps {
     readonly canvasLiveAgent: (name: string | undefined, skipId?: string) => Agent | undefined;
     readonly wakeColdTeam: (team: string, skipId?: string) => ColdWake;
     readonly probeConsumption: (agent: Agent, taskId: string) => boolean;
+    /** A session's own node team (`<zone>/<id8>`), the handle a member is known by. */
+    readonly sessionTeamOf: (agent: Agent) => string;
+    /** gh#131: the local session one of this host's own `<zone>/<id8>` handles names, if exactly one. */
+    readonly localSessionOfHandle: (ref: string) => string | undefined;
     readonly steerRelay: (agent: Agent, text: string, sender?: string) => void;
     readonly fromClause: (from: string) => string;
-    readonly armReceiptAutosend: (target: Agent, taskId: string, callerTeam: string | undefined, deliveredText: string) => void;
+    readonly sanitizeFromClause: (from: string) => string;
+    readonly armReceiptAutosend: (target: Agent, taskId: string, callerTeam: string | undefined, deliveredText: string, steerFloor: number) => void;
+    /** #114 S5: the target's session-log length, read just before a steer. */
+    readonly eventCountOf: (agent: Agent) => number;
     readonly receiptExpectationOf: (receiptTarget: string) => 'receivable' | 'process-label';
     readonly armAsyncNudge: (agent: Agent, team: string, taskId: string, delayMs: number) => void;
     readonly liveAgent: () => Agent | undefined;
@@ -159,9 +188,25 @@ export interface WireDeps {
     readonly nativeTeamsPrepare: (team: string) => Promise<NativePrepared>;
     readonly nativeTeamsRound: (prepared: Extract<NativePrepared, {
         ok: true;
-    }>, team: string, caller: string, message: string, taskId: string | undefined) => Promise<NativeRoundOutcome>;
-    readonly routeIntoAgent: (team: string, message: string, caller: string, taskId?: string) => Promise<RouteOutcome>;
+    }>, 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>;
 }
+/**
+ * #187: what a verified claim may vouch for at settlement. The signing key always (the card was
+ * fetched and its key verified); the ORIGIN only when the claim URL is that origin's root — a card
+ * fetched from a path under an origin proves the path's publisher, not the origin's host.
+ */
+export declare function settlerClaimFields(claim: {
+    ok: boolean;
+    cli?: true;
+    callerUrl?: string;
+    card?: {
+        publicKey: string;
+    };
+}, originOf: (url: string) => string): {
+    claimOrigin?: string;
+    claimKey?: string;
+};
 /**
  * Register the small wire faces on a settled web server.
  * @param webServer - the settled host web server.