@nelsonlongxiang/dsh-open-a2a-net 0.6.28 → 0.6.30

package/lib/skill/references/routing.md

@@ -17,14 +17,24 @@ polling `a2a_teams` cannot see another host's ledger.
 
 ## The ledger
 
-`__dsh_a2a/state` → `tasks`:
-
-- **pending** — routed, receipt still owed. An owed task with a delivered
-  marker is waiting on the target's turn, not lost.
-- **stale/dead** — past the stale TTL, auto-dead-lettered. A dead task that
-  actually completed at the peer is a reconciliation candidate, not a rerun.
-- **archived** — settled with a correlated receipt. The archive is bounded
-  (oldest-first eviction).
+`__dsh_a2a/state` splits the ledger into separate fields:
+
+- **`tasks`** — pending rows: routed, receipt still owed. An owed task with a
+  delivered marker is waiting on the target's turn, not lost. Each row
+  carries `settleable` (young, expected and answerable).
+- **`tasksStaleCount`** — how many pending rows are past the one-hour
+  settleable window or expect no receipt: conversational tail, not debt.
+- **`tasksDead`** — past the stale TTL (`taskStaleTtlMs`, 24h), auto-dead-
+  lettered, with `reason` and `direction` when known. A dead task that
+  actually completed at the peer is a reconciliation candidate, not a rerun;
+  a late receipt still settles it.
+- **`archived`** — rows that left the ledger, newest 64, newest first. Each
+  has `outcome` and `endedBy`: `receipt` (a correlated receipt), `echo`,
+  `abandoned` or `cancelled` (the caller ended it through
+  `/__dsh_a2a/tasks/abandon` or `/tasks/cancel`). `late: true` marks a
+  receipt that arrived after the caller ended the row; `direction` appears
+  when known. `archivedCount` and `archivedSplit` (count per outcome) cover
+  the whole archive.
 
 ## Idempotency
 

package/lib/skill/references/setup.md

@@ -0,0 +1,152 @@
+# Setup: one host, two peers, and beyond
+
+A step-by-step path from a fresh install to a working round on three shapes
+of network. Each step says WHO acts (owner or agent) and how to CHECK it
+before moving on: most "it doesn't route" reports are a skipped check.
+
+**Owner acts vs agent acts.** Installing the plugin, writing config,
+restarting, joining a session to the network, adding exact names to
+`teamJoinAllowlist`, and building canvas teams are human acts (the network
+is human-established, gh#7 N1 / gh#11 N7). An agent prepares the exact
+config, asks the owner to apply it, then verifies with the model tools. Never
+drive the loopback control routes from a shell to do the owner's part:
+presenting the operator's gesture on the operator's behalf is exactly the
+#9 hole.
+
+## 0. Preflight
+
+| Check | How | Expect |
+|---|---|---|
+| Plugin present | `a2a_whoami` | `ok: true`. `face: session` inside a session, `host` otherwise |
+| Version | `/__dsh_a2a/state` `version`, or the workbench header badge | the same version on every host you will link (0.6.28+) |
+| Clock | `date` on each host | NTP-synced: card signatures carry `expiresAt`, and the OriginClaim envelope allows ±5 min |
+
+## 1. One host: sessions talking to each other
+
+**Owner:**
+1. Install, then restart `dsh web`:
+   `dsh plugin --profile web add @nelsonlongxiang/dsh-open-a2a-net`
+2. Leave the config at its defaults. `sessionNodes: true` exposes main
+   sessions as joinable nodes; no `apiKey` is needed while the listener is
+   bound to loopback.
+3. Join each session that should collaborate: sidebar → A2A 网络 → toggle.
+   An unjoined session is invisible and refused (see
+   [membership.md](membership.md)).
+4. Give the sessions a shared team (`teamScopeRouting` is on by default, so a
+   teamless session has no network). Pick ONE of:
+   - **Canvas team (recommended):** workbench `/__dsh_a2a_nexus/` → select
+     the session cards → 建队. Canvas membership is assigned by hand.
+   - **Roster team:** add the EXACT name (for example `dsh/review`) to
+     `teamJoinAllowlist` in the workbench owner panel (header ⚙). Each
+     session then declares it with `a2a_team_join { team: "dsh/review" }`.
+     A `*`/prefix entry authorizes nothing (`[PATTERN_NO_MINT]`).
+
+**Agent, verify:**
+- `a2a_whoami`: `node.joined: true`, the handle `<zone>/<id8>`, and the
+  team under `teams.roster` or `teams.canvas`.
+- `a2a_teams`: the other session's handle is listed.
+- One sync round:
+  `a2a_route { team: "<other handle>", message: "ping: reply 'pong'" }`.
+  A local target gets up to 180 s. Continue the conversation with the
+  returned `context_id`.
+
+## 2. Two hosts that can reach each other (peers)
+
+Do section 1 on both hosts first. Then the **owner**, on BOTH hosts:
+
+1. **Reachability, both ways.** Each host must open the other's web
+   listener (LAN, VPN or tunnel). There is no built-in NAT traversal.
+2. **One shared `apiKey`.** Bind beyond loopback only with a key. The
+   delivery face `/a2a/direct` and the log face require `X-API-Key` when a
+   key is set, and a host sends ITS OWN `apiKey` on every peer request. So
+   keyed hosts that talk to each other must carry the SAME key (or both
+   none, loopback-only). A mismatch shows up as HTTP 401
+   `X-API-Key required on the delivery face`.
+3. **Announce and seed each other.** Seeding BOTH ways is what makes the
+   hosts linked: each side then reads the other's full card. One-sided
+   seeding does not link.
+
+   ```yaml
+   - id: a2a
+     name: '@nelsonlongxiang/dsh-open-a2a-net'
+     config:
+       announce: true
+       apiKey: '<same secret on every linked host>'
+       peers: ['http://<other-host>:<port>']   # the other side lists this host
+   ```
+
+   Restart. `announce` toggled from the owner panel applies on the next
+   restart.
+4. **Link the sessions across hosts with a canvas team.** Hosts default to
+   the same zone name (`team: 'dsh'`), so a remote caller `dsh/<id8>`
+   resolves to no local session. A roster declaration cannot admit it,
+   because the roster holds this host's own sessions only. The record that
+   admits it is a **canvas team naming both exact handles**. Build it in the
+   workbench (建队 with the local session, then add the remote handle):
+   - on the host that receives rounds, or
+   - on either host, once they are linked (step 3).
+
+   The other side then reads that board's `canvasOrg` from the peer's full
+   card it has cached (gh#71, recognized both ways). `a2a_probe` warms that
+   cache. Receipts flowing back are admitted the same way.
+
+   Admission is target-scoped (F5): the remote member reaches only the
+   sessions inside that canvas team. A linked peer can also edit your canvas
+   through `/__dsh_a2a/fleet-canvas-op`; your host's link gate decides.
+
+**Agent, verify on each host:**
+- `a2a_probe`: the peer is reachable. A miss is classified as `unreachable`
+  (network, port, tunnel) or `rejected` (key, signature, clock).
+- State face `remote` rows: the peer's sessions appear, with `via` set to
+  the peer URL. `a2a_teams` shows peer rows only for teams in this host's
+  joined scope (S5, `teamScopeInfo`), so an empty list is not proof that the
+  link failed.
+- One async round with a receipt:
+  `a2a_route { team: "<remote handle>", message: "...", async: true }`,
+  then check `a2a_tasks` until the row lands in `archived` with
+  `endedBy: receipt`. A peer delivery rides a 15 s transport budget:
+  `-32005` means it was delivered and is still running. Reconcile; never
+  resend.
+
+## 3. Beyond direct peers (A cannot reach C)
+
+Host-to-host forwarding is **not shipped yet**. Today a delivery reaches only
+the host it is sent to:
+- `/a2a/direct` never relays.
+- A session's `a2a_route` dials the host that publishes the team.
+- #57 Plan A (host forwarding) is designed. Its prerequisite #60 hop budget
+  has landed at ingress.
+
+Until forwarding ships, pick one:
+
+1. **Make it a peer pair.** Open a tunnel or port-forward so A reaches C,
+   then do section 2 for A↔C. This is the simplest and keeps receipts
+   end-to-end.
+2. **Delegate through B.** Route the task to a session on B, the host both
+   sides reach, and have that session route on to C and report back. Each
+   hop is its own task with its own receipt: B's ledger owns the B→C leg.
+   Keep messages self-contained and use `async: true` per hop.
+3. **Names across zones.** `delegates` publishes signed name records, so a
+   name can resolve through other zones (≤5 hops, loops fail closed). That
+   is name resolution, not message forwarding: the final delivery still
+   goes straight to the resolved host, so that host must be reachable.
+
+## 4. Callers outside a session
+
+Scripts and terminals use the `a2a-net` CLI: deposit on ONE home host, read
+a mailbox, no wake. The same rule applies: the CLI reaches only teams on its
+home host. See [cli.md](cli.md).
+
+## 5. Symptom → step
+
+| Symptom | Go back to |
+|---|---|
+| `declares no team membership` / `shares no team` | §1.4 (same host) or §2.4 (cross-host canvas ref on the target) |
+| `caller_session is required` | the caller is not a joined session (§1.3) or an external client omitted it |
+| HTTP 401 `X-API-Key required` | §2.2: keys differ between the hosts |
+| `a2a_probe` → `rejected` | §2.2 key, or §0 clock; also card signature/expiry |
+| `a2a_probe` → `unreachable` | §2.1 reachability (bind address, firewall, tunnel) |
+| peer reachable but its sessions never appear | §2.3: seeding is one-sided, or the peer did not `announce` |
+| `No live DSH session node accepts team X` | X is on another host and nothing forwards (§3), or X is not joined/live there |
+| `[PATTERN_NO_MINT]` / `[ALLOWLIST_DENY]` | §1.4: add the EXACT team name to the allowlist |
+| `[CANVAS_TEAM]` from `a2a_team_join` | canvas teams are built in the workbench, not joined by tool |

package/lib/task-ledger.js

@@ -60,7 +60,7 @@ export function briefOf(message) {
  * lazy — every read/write entry point sweeps first.
  */
 export const TASK_STALE_TTL_MS = 24 * 60 * 60_000;
-const ARCHIVE_ENDS = ['receipt', 'echo', 'abandoned', 'cancelled'];
+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)';
 /**
@@ -165,7 +165,8 @@ export class TaskLedger {
                 ...(contextId !== undefined && contextId !== '' ? { contextId } : {}),
                 ...(brief !== undefined && brief !== '' ? { brief } : {}),
                 status: 'pending',
-            }, ...this.tasks].slice(0, TASK_CAP);
+            }, ...this.tasks];
+        this.trimOwed();
         this.persist();
     }
     track(taskId, team, peer, contextId, brief) {
@@ -185,7 +186,8 @@ export class TaskLedger {
                 ...(contextId !== undefined && contextId !== '' ? { contextId } : {}),
                 ...(brief !== undefined && brief !== '' ? { brief } : {}),
                 status: 'pending',
-            }, ...this.tasks].slice(0, TASK_CAP);
+            }, ...this.tasks];
+        this.trimOwed();
         this.persist();
     }
     /**
@@ -219,7 +221,8 @@ export class TaskLedger {
                 ...(contextId !== undefined && contextId !== '' ? { contextId } : {}),
                 ...(brief !== undefined && brief !== '' ? { brief } : {}),
                 status: 'pending',
-            }, ...this.tasks].slice(0, TASK_CAP);
+            }, ...this.tasks];
+        this.trimOwed();
         this.persist();
     }
     /**
@@ -272,6 +275,7 @@ export class TaskLedger {
                 outcome: 'abandoned',
                 endedBy: 'abandoned',
                 ...(record.direction !== undefined ? { direction: record.direction } : {}),
+                ...(record.receiptExpected === false ? { receiptExpected: false } : {}),
             });
             this.persist();
             return { outcome: 'cleared', taskId, archivedAt: resolvedAt };
@@ -313,6 +317,7 @@ export class TaskLedger {
                 outcome: 'abandoned',
                 endedBy: 'cancelled',
                 ...(record.direction !== undefined ? { direction: record.direction } : {}),
+                ...(record.receiptExpected === false ? { receiptExpected: false } : {}),
             });
             this.persist();
             return {
@@ -363,6 +368,7 @@ export class TaskLedger {
                 ...(elapsedMs !== undefined ? { elapsedMs } : {}),
                 endedBy: 'receipt',
                 ...(record.direction !== undefined ? { direction: record.direction } : {}),
+                ...(record.receiptExpected === false ? { receiptExpected: false } : {}),
             });
             this.persist();
             return {
@@ -445,6 +451,7 @@ export class TaskLedger {
                 summary: ECHO_SUMMARY,
                 endedBy: 'echo',
                 ...(record.direction !== undefined ? { direction: record.direction } : {}),
+                ...(record.receiptExpected === false ? { receiptExpected: false } : {}),
             });
             settled.push(record.taskId);
         }
@@ -456,6 +463,33 @@ export class TaskLedger {
     archiveSettled(record) {
         this.archived = [record, ...this.archived].slice(0, this.archiveCap);
     }
+    /**
+     * gh#86 (chief order direct-4f596524): when the owed book exceeds
+     * TASK_CAP, the overflow rows go to the ARCHIVE as evicted - visible
+     * for audit, never silently dropped. The review seat's recommendation,
+     * chief-endorsed: the silent cap slice lost the oldest pending rows
+     * with no trace. L8 criterion: zero silently-dropped.
+     */
+    trimOwed() {
+        if (this.tasks.length <= TASK_CAP)
+            return;
+        const overflow = this.tasks.slice(TASK_CAP);
+        this.tasks = this.tasks.slice(0, TASK_CAP);
+        const now = this.now();
+        for (const row of overflow) {
+            this.archiveSettled({
+                taskId: row.taskId,
+                team: row.team,
+                peer: row.peer,
+                startedAt: row.startedAt,
+                ...(row.contextId !== undefined ? { contextId: row.contextId } : {}),
+                resolvedAt: now,
+                ...(row.brief !== undefined ? { brief: row.brief } : {}),
+                endedBy: 'evicted',
+                ...(row.direction !== undefined ? { direction: row.direction } : {}),
+            });
+        }
+    }
     /** Lazy dead-letter sweep: overdue pending rows flip status, at most once. */
     sweep(now) {
         let changed = false;
@@ -505,6 +539,7 @@ export class TaskLedger {
                             ...(typeof entry.lateReceiptAt === 'number' && Number.isFinite(entry.lateReceiptAt) ? { lateReceiptAt: entry.lateReceiptAt } : {}),
                             ...(typeof entry.endedBy === 'string' && ARCHIVE_ENDS.includes(entry.endedBy) ? { endedBy: entry.endedBy } : {}),
                             ...(entry.direction === 'inbound' || entry.direction === 'outbound' ? { direction: entry.direction } : {}),
+                            ...(entry.receiptExpected === false ? { receiptExpected: false } : {}),
                         });
                         continue;
                     }
@@ -550,6 +585,7 @@ export class TaskLedger {
                         ...(typeof entry.lateReceiptAt === 'number' && Number.isFinite(entry.lateReceiptAt) ? { lateReceiptAt: entry.lateReceiptAt } : {}),
                         ...(typeof entry.endedBy === 'string' && ARCHIVE_ENDS.includes(entry.endedBy) ? { endedBy: entry.endedBy } : {}),
                         ...(entry.direction === 'inbound' || entry.direction === 'outbound' ? { direction: entry.direction } : {}),
+                        ...(entry.receiptExpected === false ? { receiptExpected: false } : {}),
                     });
                 }
             }

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

@@ -51,14 +51,23 @@ export declare class CanvasStore {
     /** Team entries in creation order; members in add order (routing priority). */
     private teams;
     private readonly path;
+    private readonly listeners;
     /**
      * @param path - the snapshot file; an empty path keeps the store in memory.
      */
     constructor(path: string);
+    /**
+     * Observe changes: the listener runs after every write that changed the
+     * store (never on restore). A throwing listener cannot break the write.
+     * @param listener - called with no arguments.
+     * @returns the unsubscribe function.
+     */
+    onChange(listener: () => void): () => void;
     /** Load a persisted snapshot, if present and well-formed. */
     private restore;
-    /** Persist the current snapshot (no-op without a path). */
+    /** Persist the current snapshot (no-op without a path), then tell the listeners. */
     private persist;
+    private write;
     /** Every team name, in creation order. */
     list(): readonly string[];
     /** Whether the named team exists. */

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

@@ -0,0 +1,133 @@
+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 { 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 { 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 { PeerStore } from '../peer-store.ts';
+import { type TaskLedger } from '../task-ledger.ts';
+import type { TeamMembershipStore } from '../team-store.ts';
+/** Remote-team rows cached for the state face (see refreshRemoteRows). */
+export type RemoteRowsCache = {
+    at: number;
+    rows: {
+        team: string;
+        name: string;
+        origin?: string;
+        via?: string;
+        workspace?: string;
+        legacy?: boolean;
+        teams?: readonly string[];
+    }[];
+} | undefined;
+/** Everything the admin faces used to capture from `apply()`. */
+export interface AdminFaceDeps extends Pick<CanvasNotifyDeps, 'verifyOriginClaim' | 'callerLinkedToThisHost' | 'cachedCardFetch'> {
+    readonly ctx: Context;
+    readonly config: Config;
+    readonly logger: ReturnType<Context['logger']>;
+    readonly home: string;
+    readonly session: string;
+    readonly lanIp: string;
+    readonly PLUGIN_VERSION: string;
+    /** index.ts's `import.meta.url` — the base the asset roots resolve against. */
+    readonly indexUrl: string;
+    readonly controlRoute: (handler: (req: IncomingMessage, res: ServerResponse) => void) => (req: IncomingMessage, res: ServerResponse) => void;
+    readonly controlTrustedWithoutKey: (req: IncomingMessage) => boolean;
+    readonly readJsonBody: (req: IncomingMessage, res: ServerResponse, use: (body: {
+        readonly id?: unknown;
+        readonly name?: unknown;
+        readonly action?: unknown;
+    }) => void, maxBytes?: number) => void;
+    readonly peerStore: PeerStore;
+    readonly peerLinkState: (peerUrl: string) => {
+        link: 'linked' | 'stranger';
+        verified: boolean;
+    };
+    readonly originClaimHeaders: () => Record<string, string>;
+    readonly refreshRemoteRows: () => void;
+    readonly joinedSessions: JoinedSessions;
+    readonly exposureStore: ExposureStore;
+    readonly teamMemberships: TeamMembershipStore;
+    readonly cliDeposits: CliDepositStore;
+    readonly groupStore: GroupStore;
+    readonly canvasStore: CanvasStore;
+    readonly layoutStore: LayoutStore;
+    readonly taskLedger: TaskLedger;
+    readonly idempotencyStore: IdempotencyStore;
+    readonly inFlightRoutes: Map<number, InFlightRoute>;
+    readonly recentActivity: RouteActivityEntry[];
+    readonly teamAuditRing: {
+        at: number;
+        action: 'join' | 'leave' | 'archive-prune' | 'agent-less';
+        team: string;
+        id: string;
+        ok: boolean;
+        reason?: string;
+    }[];
+    readonly reportRing: {
+        at: number;
+        level: 'info' | 'warning' | 'error';
+        message: string;
+        session: string;
+        task?: string;
+    }[];
+    readonly sessionNodes: Map<string, Agent>;
+    readonly liveRoots: Map<string, Agent>;
+    readonly mountSessionNode: (agent: Agent) => void;
+    readonly coldJoinedIds: () => Promise<Set<string>>;
+    readonly prewarmStatus: {
+        state: 'off' | 'skipped:no-wake-face' | 'draining' | 'done' | 'cancelled';
+        attempted: number;
+        woken: number;
+        failed: Array<{
+            id: string;
+            error: string;
+        }>;
+    };
+    readonly reconcileStatus: {
+        state: 'off' | 'idle' | 'draining';
+        lastTickAt: number;
+        lastChecked: number;
+        woken: number;
+        rows: Array<{
+            id: string;
+            error: string;
+            attempts: number;
+            nextRetryAt: number;
+            needsRepair: boolean;
+        }>;
+    };
+    readonly id8: (id: string) => string;
+    readonly sessionLabelOf: (agent: Agent) => string;
+    readonly sessionTeamOf: (agent: Agent) => string;
+    readonly nodeMetadataOf: (agent: Agent) => {
+        name: string;
+        description: string;
+        workspace?: string;
+    };
+    readonly canvasTeamOf: (name: string) => string;
+    readonly archivedSessionFilter: () => ((id: string) => boolean) | undefined;
+    readonly pruneArchivedJoins: () => void;
+    readonly pruneCanvasMemberships: () => void;
+    readonly cardCache: Map<string, CardCacheEntry>;
+    readonly remoteRowsCache: RemoteRowsCache;
+    readonly legacyInboundCount: number;
+    readonly ownCardUrl: string;
+    ownerAllowlist: string[];
+    ownerTeamScopeInfo: boolean;
+    ownerAnnounceRestartPending: boolean;
+}
+/**
+ * Register the admin faces on a settled web server.
+ * @param webServer - the settled host web server.
+ * @param d - the captures listed on {@link AdminFaceDeps}.
+ */
+export declare function registerAdminFaces(webServer: WebServer, d: AdminFaceDeps): void;

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

@@ -0,0 +1,74 @@
+/**
+ * Canvas change notification (owner ruling 2026-10-29: single owner + mirror).
+ *
+ * A canvas team belongs to the host that created it. Peers MIRROR it from the
+ * owner's full card (`canvasOrg`, rendered through the state face's
+ * `peerOrg`) and EDIT it through the fleet relay (`/__dsh_a2a/fleet-canvas-op`
+ * → the owner's `/a2a/canvas-op`). Nothing is replicated, so there is no
+ * merge: the owner's store is the single truth. What was missing is
+ * freshness — a mirror only moved when the 60s card-cache window lapsed.
+ *
+ * This face closes that gap with a content-free ping:
+ * - SEND: any change to this host's canvas store (local board, a peer's
+ *   canvas-op, a leave/archive prune) schedules one debounced
+ *   `POST /a2a/canvas-changed` to every tracked peer that is linked to this
+ *   host by the same predicate the card face uses to serve the full card —
+ *   exactly the peers that can see `canvasOrg` at all. The body is empty:
+ *   the ping says "re-read my card", never what changed.
+ * - RECEIVE: a verified OriginClaim from a TRACKED peer marks that peer's
+ *   cached card stale (the card stays readable — no frame flicker) and
+ *   refetches it through the shared single-flight cache; the board's next
+ *   3s poll renders the new org. Per-peer rate limit; a caller whose claimed
+ *   URL is not exactly a tracked peer with a cached card is refused before
+ *   its claim is verified (nothing is fetched on its say-so), an unsigned one
+ *   right after.
+ * @module src/faces/canvas-notify
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import type WebServer from '@deepseek-ai/dsh-host-webserver';
+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';
+/** 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. */
+export declare const CANVAS_REFRESH_MIN_GAP_MS = 1000;
+/** The captures this face needs from `apply()`. */
+export interface CanvasNotifyDeps {
+    readonly ctx: Context;
+    readonly logger: ReturnType<Context['logger']>;
+    readonly peerStore: PeerStore;
+    readonly canvasStore: CanvasStore;
+    readonly cardCache: Map<string, CardCacheEntry>;
+    readonly originClaimHeaders: () => Record<string, string>;
+    readonly verifyOriginClaim: (req: IncomingMessage) => Promise<{
+        ok: true;
+        caller: string;
+        callerUrl: string;
+        card: A2aPeerCard;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    readonly callerLinkedToThisHost: (caller: string, callerUrl: string, callerCard: A2aPeerCard | undefined) => boolean;
+    readonly cachedCardFetch: (url: string) => Promise<A2aPeerCard | undefined>;
+}
+/**
+ * Re-read one peer's card now. Each pass pre-stales the entry (the literal
+ * carries no missAt) so it is a GENUINE refetch: pass 1 may join a flight
+ * that started before the peer's change; pass 2 always starts after the
+ * first settled — that one is the answer. A miss keeps the last good card
+ * inside cachedCardFetch itself (the missAt window); there is nothing to
+ * restore here.
+ * @param d - the card cache and its single-flight fetch.
+ * @param url - the tracked peer URL.
+ */
+export declare function refreshPeerCard(d: Pick<CanvasNotifyDeps, 'cardCache' | 'cachedCardFetch'>, url: string): Promise<void>;
+/**
+ * Register the receive face and subscribe the send side to the canvas store.
+ * @param webServer - the settled host web server.
+ * @param d - the captures listed on {@link CanvasNotifyDeps}.
+ */
+export declare function registerCanvasNotify(webServer: WebServer, d: CanvasNotifyDeps): void;