@nelsonlongxiang/dsh-open-a2a-net 0.6.38 → 0.6.40

package/lib/skill/references/setup.md

@@ -1,153 +1,156 @@
-# 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 |
-
-## Human seat names
-
-The owner can open the workbench header ⚙, select a local session under “会话席位名”, and explicitly save a stable display name (up to 64 characters; a name shaped like a route address such as `dsh/66abc2cf` is refused so it cannot pass for another session). Empty input clears the label. The `seatNames` map is stored in the home patch layer and hot-applies; cards and the board prefer it over the session title, and `a2a_whoami` / `a2a-net teams <name>` expose it. It never changes the route handle, join state or admission. Agents must ask the owner rather than self-name: A2A tool arguments containing `seatName`/`seatNames` are refused; no naming model tool exists. The owner control API keeps its existing apiKey/loopback trust model, not a sandbox against local shell or config-file writers.
-
-## 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
-   (add or remove members, dissolve a team) 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)
-
-Home-host one-hop forwarding shipped in 0.6.34 and defaults **on from 0.6.38**. Explicit `forwardDirect: false` restores local-only CLI delivery. It only follows a local miss for a bound-signed, online CLI deposited on that home, inside the unchanged sender scope. A must directly link B's receiving member (all advertised potential receivers for a canvas), and B must link the CLI and pin A as home. The home must not be isolated and any inbound Guard prevents a second forward. The outbound hop budget remains DEFAULT-1. No links are auto-created or relaxed.
-
-Long forwarded work should use async `route` plus `inbox --wait --renew`, not expect a 15s `--sync` transport window to cover an entire model turn. A late final still produces the original task's receipt, and the forwarded row keeps selected-peer receiver facts for enforced settlement.
-
-Other connectivity options (not authority bypasses):
-
-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 home can forward eligible requests one hop under section 3; an online deposit alone grants no remote scope. 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 |
+# 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 |
+
+## Human seat names
+
+The owner can open the workbench header ⚙, select a local session under “会话席位名”, and explicitly save a stable display name (up to 64 characters; a name shaped like a route address such as `dsh/66abc2cf` is refused so it cannot pass for another session). Empty input clears the label. The `seatNames` map is stored in the home patch layer and hot-applies; cards and the board prefer it over the session title, and `a2a_whoami` / `a2a-net teams <name>` expose it. It never changes the route handle, join state or admission. Agents must ask the owner rather than self-name: A2A tool arguments containing `seatName`/`seatNames` are refused; no naming model tool exists. The owner control API keeps its existing apiKey/loopback trust model, not a sandbox against local shell or config-file writers.
+
+## 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
+   (add or remove members, dissolve a team) 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)
+
+Home-host one-hop forwarding shipped in 0.6.34 and defaults **on from 0.6.38**. Explicit `forwardDirect: false` restores local-only CLI delivery. It only follows a local miss for a bound-signed, online CLI deposited on that home, inside the unchanged sender scope. A must directly link B's receiving member (all advertised potential receivers for a canvas), and B must link the CLI and pin A as home. The home must not be isolated and any inbound Guard prevents a second forward. The outbound hop budget remains DEFAULT-1. No links are auto-created or relaxed.
+
+Long forwarded work should use async `route` plus `inbox --wait --renew`, not expect a 15s `--sync` transport window to cover an entire model turn. A late final still produces the original task's receipt, and the forwarded row keeps selected-peer receiver facts for enforced settlement.
+
+Other connectivity options (not authority bypasses):
+
+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
+
+For an always-on CLI home that survives DSH restarts, run the network layer without a DSH instance: `a2a-net serve` — deployment, service files, linking and the public-internet caveats are in `docs/guides/standalone-node.md` of the repository.
+
+
+Scripts and terminals use the `a2a-net` CLI: deposit on ONE home host, read
+a mailbox, no wake. The home can forward eligible requests one hop under section 3; an online deposit alone grants no remote scope. 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-auth.js

@@ -32,7 +32,11 @@ export const VIA_OF = {
 /** The refusal text of a decision, or undefined when admitted — the shape the faces have always read. */
 export const refusalOf = (admission) => (admission.ok ? undefined : admission.refusal);
 const admitted = (rule, basis = []) => ({ ok: true, via: VIA_OF[rule], rule, basis });
-const refused = (refusal) => ({ ok: false, refusal });
+/** #282 S1: a refusal may carry the one step the caller (or this host's operator) can take next. */
+const refused = (refusal, next) => ({ ok: false, refusal, ...(next !== undefined ? { next } : {}) });
+/** The next step of a refused decision, or undefined. */
+export const nextOf = (a) => (a.ok ? undefined : a.next);
+const linkNext = (caller, target) => `ask this host's operator to put ${caller} in a canvas team${target !== undefined ? ` with ${target}` : ''} in the A2A workbench, or route through a member of a team you already share`;
 const ZONE_ID8 = /^[a-z0-9-]+\/[0-9a-f]{8}$/i;
 const teamlessText = (caller) => `caller "${caller}" declares no team membership on this host's roster — a teamless node has no network (S3 phase-3 admission). Declare a shared team on both ends, or route through a teamed member.`;
 /**
@@ -178,7 +182,7 @@ export function sameZoneAdmission(r, caller, targetTeam) {
                 return hit;
             return refused(declared.size === 0
                 ? teamlessText(caller)
-                : `caller "${caller}" shares no team with target "${targetTeam}" — declared [${[...declared.keys()].join(', ')}], target links [${[...links].join(', ')}] (F5 target-level admission: a host-level link alone does not open every session team).`);
+                : `caller "${caller}" shares no team with target "${targetTeam}" — declared [${[...declared.keys()].join(', ')}], target links [${[...links].join(', ')}] (F5 target-level admission: a host-level link alone does not open every session team).`, linkNext(caller, targetTeam));
         }
     }
     const hit = pass(t => routable.has(t) || otherLocalDeclarations.has(t));
@@ -186,7 +190,7 @@ export function sameZoneAdmission(r, caller, targetTeam) {
         return hit;
     return refused(declared.size === 0
         ? teamlessText(caller)
-        : `caller "${caller}" declares teams [${[...declared.keys()].join(', ')}] — none is routable on this node (shared-team admission). Declare a shared team on both ends, or route through a teamed member.`);
+        : `caller "${caller}" declares teams [${[...declared.keys()].join(', ')}] — none is routable on this node (shared-team admission). Declare a shared team on both ends, or route through a teamed member.`, linkNext(caller, targetTeam));
 }
 /**
  * W1: the joined-face gate for the LOCAL dispatch candidate — only a
@@ -216,7 +220,7 @@ export function callerAdmission(r, caller, targetTeam, cliProof) {
     if (!r.teamScopeRouting)
         return admitted('scope-off');
     if (caller === '') {
-        return refused('caller_session is required — anonymous deliveries are refused (S3 phase-3b). Pass caller_session as <zone>/<id8>.');
+        return refused('caller_session is required — anonymous deliveries are refused (S3 phase-3b). Pass caller_session as <zone>/<id8>.', 'send caller_session as your <zone>/<id8> handle (a2a-net does this for you)');
     }
     if (caller === r.zone)
         return admitted('host-face');
@@ -228,21 +232,21 @@ export function callerAdmission(r, caller, targetTeam, cliProof) {
         const basis = r.canvasNames().filter(name => r.canvasRemoteMembersOf(name).includes(caller)).map(name => r.canvasTeamOf(name));
         if (basis.length > 0)
             return admitted('remote-ref-foreign', basis);
-        return refused(`caller "${caller}" has no operator-established link on this node — cross-host admission requires a canvas remote membership this host's operator added (N3/N4: the caller's own card claims are self-description, not links). Ask this host's operator to add the member in the A2A workbench, or route through a linked member.`);
+        return refused(`caller "${caller}" has no operator-established link on this node — cross-host admission requires a canvas remote membership this host's operator added (N3/N4: the caller's own card claims are self-description, not links). Ask this host's operator to add the member in the A2A workbench, or route through a linked member.`, linkNext(caller, targetTeam));
     }
     // A foreign CLI handle is never a free-form node fact: its operator link,
     // pinned home, bound signer, and fresh online row must ALL hold.
     if (CLI_HANDLE_RE.test(caller) && !r.cliDeposited(caller)) {
         const basis = r.canvasNames().filter(name => r.canvasRemoteMembersOf(name).includes(caller)).map(name => r.canvasTeamOf(name));
         if (basis.length === 0)
-            return refused(`remote CLI ${caller} has no operator-established canvas link`);
+            return refused(`remote CLI ${caller} has no operator-established canvas link`, linkNext(caller, targetTeam));
         const home = r.cliHomeOf?.(caller);
         if (home === undefined)
-            return refused(`remote CLI ${caller} home is not pinned`);
+            return refused(`remote CLI ${caller} home is not pinned`, `ask this host's operator to pin ${caller}'s home host when adding it to the canvas team (workbench member dialog)`);
         if (cliProof?.bound !== true || cliHomeOrigin(cliProof.origin) !== home || cliHomeOrigin(cliProof.viaUrl) !== home)
-            return refused(`remote CLI ${caller} signer does not match pinned home`);
+            return refused(`remote CLI ${caller} signer does not match pinned home`, `send through ${caller}'s pinned home host only`);
         if (cliProof.online !== true)
-            return refused(`remote CLI ${caller} is offline or home card could not be read`);
+            return refused(`remote CLI ${caller} is offline or home card could not be read`, 'run `a2a-net publish` on the home host, then send again with a new task id');
         return admitted('remote-ref-cli', basis);
     }
     // Free-form label: only this host's own node facts (V3).
@@ -257,7 +261,7 @@ export function callerAdmission(r, caller, targetTeam, cliProof) {
     // gh#45: a deposited CLI handle is a published node fact of this host.
     if (r.cliDeposited(caller))
         return admitted('cli-deposit');
-    return refused(`caller_session "${caller}" matches no node fact on this host (joined session id, live node label, or deposited CLI handle) — free-form caller labels are self-description and are not admissible (N3). Pass caller_session as <zone>/<id8> with an operator-established link.`);
+    return refused(`caller_session "${caller}" matches no node fact on this host (joined session id, live node label, or deposited CLI handle) — free-form caller labels are self-description and are not admissible (N3). Pass caller_session as <zone>/<id8> with an operator-established link.`, 'send caller_session as a <zone>/<id8> handle this host has linked; free-form labels are never admitted');
 }
 /** Revalidate only mutable operator authority, not already-verified birth-time identity or liveness. */
 export function recheckRemoteCliAuthorization(r, auth) {

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

@@ -0,0 +1,9 @@
+/** First 8 hex of sha256 over the base64 SPKI DER public key; '' when there is no key. */
+export declare function canvasOwnerFingerprint(publicKey: string | undefined): string;
+/** Split `<zone>/canvas/<name>@<fp8>` into the plain team and the owner fingerprint. */
+export declare function splitCanvasOwner(team: string): {
+    team: string;
+    owner?: string;
+};
+/** The display/routing id of a canvas team owned by the card holding `publicKey`. */
+export declare function qualifiedCanvasId(team: string, publicKey: string | undefined): string;

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

@@ -39,6 +39,11 @@ export interface CliMail {
     /** gh#113: set when `text` was cut to MAILBOX_TEXT_CAP; `chars` is the original length. */
     readonly truncated?: true;
     readonly chars?: number;
+    /**
+     * #298: a receipt for a forward this host already answered synchronously — the CLI got the reply on the
+     * HTTP answer, so this copy is a duplicate. Kept in full (never dropped); readers may fold it.
+     */
+    readonly dup?: 'sync-answered';
 }
 /** gh#113: one mailbox read — the rows plus what a reader needs to notice loss. */
 export interface CliMailbox {
@@ -101,7 +106,7 @@ export declare class CliDepositStore {
         description: string;
         offline: boolean;
     }>;
-    mail(handle: string, from: string, text: string): void;
+    mail(handle: string, from: string, text: string, dup?: 'sync-answered'): 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;