@nelsonlongxiang/dsh-open-a2a-net 0.6.27 → 0.6.29

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

@@ -272,6 +272,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 +314,7 @@ export class TaskLedger {
                 outcome: 'abandoned',
                 endedBy: 'cancelled',
                 ...(record.direction !== undefined ? { direction: record.direction } : {}),
+                ...(record.receiptExpected === false ? { receiptExpected: false } : {}),
             });
             this.persist();
             return {
@@ -363,6 +365,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 +448,7 @@ export class TaskLedger {
                 summary: ECHO_SUMMARY,
                 endedBy: 'echo',
                 ...(record.direction !== undefined ? { direction: record.direction } : {}),
+                ...(record.receiptExpected === false ? { receiptExpected: false } : {}),
             });
             settled.push(record.taskId);
         }
@@ -505,6 +509,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 +555,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

@@ -7,7 +7,11 @@
  * `<team>/canvas/<name>` resolves the first live local member, wakes the
  * first cold local one, then falls through to the remote members in order
  * (the directory resolves their handles; remote nodes never wake from
- * here). Membership order is the routing priority (member list order),
+ * here). The dispatching session itself is exempt from the local tiers
+ * (issue #41: the self-route rule extends to canvas — an initiator
+ * occupying a member slot never captures its own dispatch, which would
+ * only echo home; the seam lives in the dispatch layer, the store stays
+ * pure). Membership order is the routing priority (member list order),
  * preserved verbatim on disk. Plain JSON, one writer (the control routes),
  * read fresh by the state route.
  * @module @nelsonlongxiang/dsh-open-a2a-net/canvas-store

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

@@ -1,5 +1,11 @@
 /** Owner ruling ③: the default AND maximum online window. */
 export declare const CLI_DEPOSIT_TTL_MS: number;
+/**
+ * gh#47 tombstone bound: expired deposits stay visible as OFFLINE rows
+ * (newest TOMBSTONE_CAP keep their handle/name so team refs never dangle
+ * silently) — the owner manages CLI nodes like session nodes.
+ */
+export declare const CLI_TOMBSTONE_CAP = 16;
 /** Owner ruling ①: <agent-name>/<uuid·8B>. The name is [a-z0-9-]{1,32}. */
 export declare const CLI_HANDLE_RE: RegExp;
 /** One deposited CLI identity. */
@@ -11,6 +17,12 @@ export interface CliDeposit {
     readonly cardJson: string;
     readonly depositedAt: number;
     readonly expiresAt: number;
+    /**
+     * gh#47 tombstone: set when the deposit expired — the row stays (offline)
+     * so the directory/board keeps the member visible and team refs never
+     * dangle silently. A re-publish (same handle, same key) un-tombstones.
+     */
+    expiredAt?: number;
 }
 /** One mailbox entry for a deposited handle. */
 export interface CliMail {
@@ -37,17 +49,34 @@ export declare class CliDepositStore {
     };
     revoke(handle: string): boolean;
     /** Active deposits (sweeping expired ones — ruling ③ auto-deregister). */
+    /** LIVE deposits only (tombstones excluded — the control list is the
+     *  online roster; offline rows ride directoryRows for the board). */
     list(): readonly CliDeposit[];
     get(handle: string): CliDeposit | undefined;
-    /** Card-serve rows: the handle + display name, marked cli (no wake). */
+    /** Card-serve rows: LIVE deposits only (an expired card 404s). */
     cardRows(): Array<{
         team: string;
         name: string;
         description: string;
     }>;
+    /**
+     * gh#47 directory rows: LIVE + TOMBSTONE (offline) — the board renders
+     * offline member cards grayed but PRESENT, so a canvas ref to an expired
+     * CLI never dangles silently. Re-publish un-tombstones (same handle).
+     */
+    directoryRows(): Array<{
+        team: string;
+        name: string;
+        description: string;
+        offline: boolean;
+    }>;
     mail(handle: string, from: string, text: string): void;
     readMail(handle: string): readonly CliMail[];
     private sweep;
+    /** Mark one row expired (tombstone) and persist. */
+    private markExpired;
+    /** Keep at most TOMBSTONE_CAP offline rows — oldest evictions fall off. */
+    private pruneTombstones;
     private persist;
     private restore;
 }

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

@@ -0,0 +1,132 @@
+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 { 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 {
+    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/index.d.ts

@@ -191,11 +191,19 @@ export interface Config {
     /** Backoff ceiling; corrupt-log rows park as needs-repair and never retry. */
     readonly wakeReconcileMaxBackoffMs: number;
     /**
-     * S4: joinable-team patterns for a2a_team_join — exact names or
-     * trailing-`*` prefixes. Empty list denies every join (default).
+     * 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[];
-    /** S3 (queued): team-scoped routing admission. Enforcement off by default. */
+    /**
+     * 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

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

@@ -18,6 +18,22 @@ export declare const FAILURE_PENALTY = 100;
 export declare const SUCCESS_REWARD = 100;
 /** Score floor: at or below this a non-seed peer is evicted. */
 export declare const EVICTION_FLOOR = 0;
+/**
+ * Eviction cooldown (the zombie-referral breaker): an evicted dead address
+ * is refused by {@link PeerStore.offer} for this long — without it the
+ * address comes straight back through a linked peer's card advertising
+ * (evict → learn → fail → evict forever; observed grinding .156:3081 down
+ * 3400 points). v1 keeps the window FIXED at 24h (dead-letter TTL
+ * convention); progressive backoff is a future note, not this slice.
+ */
+export declare const EVICTION_COOLDOWN_MS: number;
+/** Ledger bound: the newest 64 evictions survive (LRU by evictedAt). */
+export declare const EVICTION_LEDGER_CAP = 64;
+/** One eviction-ledger row: when a URL was evicted (epoch ms). */
+export interface EvictionRecord {
+    readonly url: string;
+    readonly evictedAt: number;
+}
 /** One tracked peer. */
 export interface PeerRecord {
     readonly url: string;
@@ -36,6 +52,8 @@ export interface PeerRecord {
 /** The persisted store document (whole-file read/write, small by design). */
 export interface PeerStoreSnapshot {
     readonly peers: readonly PeerRecord[];
+    /** Eviction ledger (gh#46): absent on pre-cooldown files = empty. */
+    readonly evictions?: readonly EvictionRecord[];
 }
 /**
  * Bounded, quality-scored peer collection with whole-file persistence.
@@ -48,12 +66,15 @@ export declare class PeerStore {
     private readonly cap;
     private readonly persistDebounceMs;
     private readonly peers;
+    /** Eviction ledger (gh#46): url → when it was evicted. Seeds never enter. */
+    private readonly evictions;
+    private readonly now;
     /**
      * @param seeds - the configured seed URLs; always retained (never evicted).
      * @param path - persistence file (`<dsh-home>/a2a/peers.json`); empty = no persistence.
      * @param cap - peer bound, seeds included (default {@link PEER_CAP}).
      */
-    constructor(seeds: readonly string[], path: string, cap?: number, persistDebounceMs?: number);
+    constructor(seeds: readonly string[], path: string, cap?: number, persistDebounceMs?: number, now?: () => number);
     /**
      * Every tracked peer URL: seeds first (in first-tracked order), then
      * offered peers by score descending (equal scores keep first-tracked order).
@@ -131,6 +152,8 @@ export declare class PeerStore {
     bySession(session: string): string | undefined;
     /** Load a persisted snapshot on construction, if present. */
     private restore;
+    /** Keep the ledger at its LRU bound: the oldest evictions fall off. */
+    private pruneLedger;
     /**
      * Persist the current peer set (no-op when no path was configured).
      * Writes are debounced and asynchronous: a sweep that settles dozens of

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

@@ -0,0 +1,56 @@
+/**
+ * Recursion guard (#60, first step: the hop budget) per
+ * docs/protocol/recursion-guard.md. State rides the payload: the origin
+ * mints the envelope with a full budget, every forwarded leg decrements,
+ * and a zero-budget arrival is refused with a STRUCTURED budget-exhausted
+ * error — silent swallowing is forbidden. The visited set (protocol §4.3)
+ * is the SECOND step and is deliberately absent here.
+ *
+ * Wire form: the X-A2A-Guard header carries a base64 JSON payload
+ * { visitToken, hopBudget, deadlineAt? }. An ABSENT header means a
+ * non-forwarding origin: the receiver grants the default one-shot budget
+ * and records guardMode 'default' (protocol §6 — old peers are
+ * constrained, not broken). Parse cost is O(1) for the budget path.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/recursion-guard
+ */
+export declare const DEFAULT_HOP_BUDGET = 4;
+/** Wire code for a zero-budget arrival (cluster-C registry, after -32006). */
+export declare const WIRE_ERROR_BUDGET_EXHAUSTED = -32007;
+/** The guard payload as it travels on the wire. */
+export interface RecursionGuard {
+    readonly visitToken: string;
+    readonly hopBudget: number;
+    readonly deadlineAt?: number;
+}
+export type GuardVerdict = {
+    readonly kind: 'ok';
+    readonly guard: RecursionGuard;
+    readonly mode: 'explicit' | 'default';
+} | {
+    readonly kind: 'budget-exhausted';
+};
+/**
+ * Ingress check: parse the header, validate the budget, fail closed. A
+ * malformed payload falls back to the default budget (a guard that cannot
+ * be evaluated must not reject honest first-hop traffic; the budget bound
+ * still applies). hopBudget <= 0 on arrival ⇒ budget-exhausted.
+ */
+export declare function checkGuardAtIngress(header: string | undefined): GuardVerdict;
+/** Mint the outbound guard for a first-hop dispatch (full budget at origin). */
+export declare function mintGuard(): RecursionGuard;
+/** Serialize for the X-A2A-Guard header. */
+export declare function guardHeader(guard: RecursionGuard): string;
+/**
+ * The ingress refusal path (gh#60): budget-exhausted answers the structured
+ * error, records the receiptless ledger row, and reports true (the caller
+ * returns). The whole response lives here so the ingress seam stays ONE
+ * line (the index.ts ratchet pays-as-it-goes: no net line growth).
+ */
+export declare function refuseIfBudgetExhausted(req: {
+    headers: Record<string, unknown>;
+}, res: {
+    writeHead: (status: number, headers: Record<string, string | number>) => void;
+    end: (body: string) => void;
+}, team: string, caller: string, taskId: string, ledger: {
+    trackReceiptless: (taskId: string, team: string, peer: string, contextId?: string, brief?: string) => void;
+}): boolean;

package/lib/types/runtime.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared A2A runtime types (gh#77): shapes that used to be declared inside
+ * `apply()` and are now read by the face modules as well.
+ * @module src/runtime
+ */
+import type { A2aPeerCard } from './types.ts';
+/**
+ * Recent routing activity for the network panel: a bounded ring of the
+ * latest inbound and outbound route outcomes, newest last. The state route
+ * serves a copy; the panel derives unread badges from new entries.
+ */
+export interface RouteActivityEntry {
+    readonly ts: number;
+    readonly dir: 'in' | 'out';
+    readonly team: string;
+    readonly peer: string;
+    readonly ok: boolean;
+}
+/**
+ * In-flight outbound routes: a route registers on dial and unregisters on
+ * settlement, so the panel can show collaboration in progress ("who is
+ * waiting on whom") — the state route serves a snapshot.
+ */
+export interface InFlightRoute {
+    readonly id: number;
+    readonly team: string;
+    readonly peer: string;
+    readonly startedAt: number;
+}
+/** One peer-card cache entry: when it was fetched and what came back. */
+export interface CardCacheEntry {
+    at: number;
+    card: A2aPeerCard | undefined;
+}

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

@@ -120,6 +120,12 @@ export interface ArchivedRecord {
     readonly endedBy?: ArchiveEnd;
     /** gh#31: which side of the wire the row served, copied from the owed row (absent on rows archived before the field). */
     readonly direction?: 'inbound' | 'outbound';
+    /**
+     * gh#68: copied from the owed row when it awaited no receipt, so a tidied
+     * fire-forget expiry is not read as a send we gave up on. Only `false` is
+     * ever stored; absent means a receipt was owed (or the row predates the field).
+     */
+    readonly receiptExpected?: false;
 }
 /**
  * How one archived row ended (gh#31). The recorded field wins; legacy rows