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

package/lib/recursion-guard.js

@@ -0,0 +1,78 @@
+/**
+ * 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 const DEFAULT_HOP_BUDGET = 4;
+/** Wire code for a zero-budget arrival (cluster-C registry, after -32006). */
+export const WIRE_ERROR_BUDGET_EXHAUSTED = -32007;
+/**
+ * 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 function checkGuardAtIngress(header) {
+    if (header === undefined || header === '') {
+        return { kind: 'ok', guard: { visitToken: '', hopBudget: DEFAULT_HOP_BUDGET }, mode: 'default' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(header, 'base64').toString('utf8'));
+    }
+    catch {
+        return { kind: 'ok', guard: { visitToken: '', hopBudget: DEFAULT_HOP_BUDGET }, mode: 'default' };
+    }
+    const hopBudget = parsed?.hopBudget;
+    if (typeof hopBudget !== 'number' || !Number.isInteger(hopBudget)) {
+        return { kind: 'ok', guard: { visitToken: '', hopBudget: DEFAULT_HOP_BUDGET }, mode: 'default' };
+    }
+    if (hopBudget <= 0)
+        return { kind: 'budget-exhausted' };
+    const visitToken = typeof parsed.visitToken === 'string'
+        ? String(parsed.visitToken)
+        : '';
+    const deadlineRaw = parsed.deadlineAt;
+    return {
+        kind: 'ok',
+        guard: { visitToken, hopBudget, ...(typeof deadlineRaw === 'number' ? { deadlineAt: deadlineRaw } : {}) },
+        mode: 'explicit',
+    };
+}
+/** Mint the outbound guard for a first-hop dispatch (full budget at origin). */
+export function mintGuard() {
+    return {
+        visitToken: Array.from({ length: 16 }, () => Math.floor(Math.random() * 16).toString(16)).join(''),
+        hopBudget: DEFAULT_HOP_BUDGET,
+    };
+}
+/** Serialize for the X-A2A-Guard header. */
+export function guardHeader(guard) {
+    return Buffer.from(JSON.stringify(guard), 'utf8').toString('base64');
+}
+/**
+ * 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 function refuseIfBudgetExhausted(req, res, team, caller, taskId, ledger) {
+    const verdict = checkGuardAtIngress(req.headers['x-a2a-guard']);
+    if (verdict.kind !== 'budget-exhausted')
+        return false;
+    ledger.trackReceiptless(taskId, team, caller === '' ? 'unknown' : caller, undefined, 'budget-exhausted at ingress (hopBudget=0)');
+    const payload = JSON.stringify({ error: 'budget-exhausted: the hop budget is spent (recursion-guard #60) — this delivery traversed its full forwarding allowance and is refused at ingress', code: WIRE_ERROR_BUDGET_EXHAUSTED, team, task_status: 'TASK_STATE_FAILED' });
+    res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+    res.end(payload);
+    return true;
+}

package/lib/runtime.js

@@ -0,0 +1 @@
+export {};

package/lib/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: a2a-network
-description: Use when a task needs cross-session or cross-node collaboration over the DSH A2A network — joining and teaming, routing work to remote teams and agents, reconciling receipts and the task ledger, and reading the A2A workbench (/__dsh_a2a_nexus/). Covers admission rules, the receipt contract, and the failure shapes that look like bugs but are contract semantics.
+description: Use when a task needs cross-session or cross-node collaboration over the DSH A2A network — setting it up (install, config, apiKey, peers, canvas links for one host, two peers, or hosts that cannot reach each other), joining and teaming, routing work to remote teams and agents, reconciling receipts and the task ledger, and reading the A2A workbench (/__dsh_a2a_nexus/). Covers admission rules, the receipt contract, and the failure shapes that look like bugs but are contract semantics.
 ---
 
 # DSH A2A Network
@@ -27,6 +27,20 @@ surface on every node.
   deposited on ONE home host for up to 4h, with a mailbox instead of a
   wakeable session. See [cli.md](references/cli.md).
 
+## Setting up
+
+Start with [setup.md](references/setup.md). It is a checked path for three
+network shapes:
+- **one host**: install, join the sessions, give them a shared team;
+- **two hosts that reach each other**: one shared `apiKey`, `announce` plus
+  peers seeded both ways, and a canvas team naming both handles;
+- **hosts that cannot reach each other**: host forwarding is not shipped
+  yet (#57), so tunnel or delegate per hop.
+
+The owner does the gestures (install, config, join, allowlist, canvas). The
+agent prepares the exact config and verifies each step with `a2a_whoami`,
+`a2a_probe`, `a2a_teams` and one round with a receipt.
+
 ## Routing (a2a_route)
 
 ```text
@@ -36,10 +50,15 @@ a2a_route { team: "<zone>/<id8 or canvas name>", message, context_id?, async? }
 - `async: true` delivers without waiting (`delivered:true` + task id); the
   target routes a receipt — a message starting `[A2A receipt] task <id>` —
   back to your team.
-- Sync (default) waits for the round's final answer. If the 15s transport
-  budget fires first, the result is **-32005 DELIVERED-UNSETTLED**: the
-  delivery landed and the peer keeps executing. **Never re-dispatch blindly**
-  — reconcile via the task id (the receipt or `a2a_teams` coordinates) instead.
+- Sync (default) waits for the round's final answer. A target on this host
+  gets up to 180s; past that the tool answers the delivered shape
+  (`TASK_STATE_DELIVERED`) and the receipt contract carries the rest. A
+  remote peer's delivery rides a 15s transport budget; if it fires first, the
+  result is **-32005 DELIVERED-UNSETTLED**: the delivery landed and the peer
+  keeps executing. Either way, **never re-dispatch blindly** — reconcile via
+  the task id (the receipt, `a2a_status` activity, or `a2a_tasks`) instead.
+- Model tools cannot route to the bare process team (`<zone>` alone, the
+  host's own mailbox): target a session handle or a canvas team.
 - `context_id` from a previous reply continues that conversation.
 
 ## Membership rules
@@ -55,10 +74,15 @@ a2a_route { team: "<zone>/<id8 or canvas name>", message, context_id?, async? }
 
 ## Reading the state
 
-`__dsh_a2a/state` (per node) carries `sessions` (live/joined), `sessionTeams`,
-`remote` (peer session rows with `origin` = node label + LAN IP and `via` =
-the peer URL), `activity` (routing ring), `tasks` (the ledger: pending /
-stale / archived). The A2A workbench (`/__dsh_a2a_nexus/`, merged responsive
+`__dsh_a2a/state` (per node, key-gated like every control route) carries
+`sessions` (live/joined, with their teams), `canvas` (canvas teams; remote
+members show `remote: true`), `remote` (peer session rows with `origin` =
+node label + LAN IP and `via` = the peer URL), `activity` (routing ring),
+and the ledger: `tasks` (pending, each with `settleable`),
+`tasksStaleCount`, `tasksDead`, and `archived` (newest 64 settled rows, each
+with `outcome`, `endedBy` and `late`) plus `archivedCount` /
+`archivedSplit`. `sessionTeams` is a card field, not a state field. The A2A
+workbench (`/__dsh_a2a_nexus/`, merged responsive
 shell since 0.6.2 — the 2D planning board is the stage, directory / ledger /
 activity / plan ride a collapsible rail, narrow screens get a drawer)
 renders the same data for humans.
@@ -82,6 +106,7 @@ renders the same data for humans.
 
 ## Details
 
+- [setup.md](references/setup.md) — setup and checks: one host, two peers, beyond direct peers
 - [routing.md](references/routing.md) — receipts, idempotency, ledger anatomy
 - [discovery.md](references/discovery.md) — cards, peer boundary model, invisibility
 - [membership.md](references/membership.md) — join/leave, allowlist, canvas teams

package/lib/skill/references/cli.md

@@ -24,7 +24,10 @@ ten model tools.
 
 - `a2a-net publish` deposits the signed CLI card on the home host
   (`/__dsh_a2a/cli-deposit`, a control route: key-gated like every write).
-  The deposit lives at most 4h, then deregisters; publish again to return.
+  The deposit lives at most 4h. An expired deposit is no longer routable and
+  its card is no longer served, but it stays in the host's directory as an
+  OFFLINE row (gh#47; the newest 16 are kept) so canvas refs to it never
+  dangle silently. Publish again (same handle, same key) to come back.
 - While deposited, the host serves the card at
   `<home>/a2a/cli/<handle>/.well-known/agent-card.json` and lists the handle
   in its directory as "cli — deposited identity (no wake; mailbox)".
@@ -36,8 +39,14 @@ ten model tools.
 
 ## Sending
 
-- `a2a-net route <team> <message…>` delivers an async round with a signed
-  OriginClaim envelope to the HOME host's `/a2a/direct`.
+- `a2a-net route <team> <message…>` delivers a round with a signed
+  OriginClaim envelope to the HOME host's `/a2a/direct`. It is async by
+  default: the receipt comes back to `a2a-net inbox`.
+- `--sync` waits for the target's reply and prints it:
+  `reply from <team> · task <id> · context <ctx>` followed by the reply text.
+  When the round has not settled (status other than completed) a warning
+  goes to stderr: reconcile by task id before re-sending.
+- `--context ID` continues that conversation (sends it as `context_id`).
 - Direct delivery does not relay: only teams on the home host are reachable.
   A team on another host answers "No live DSH session node accepts team".
 - Admission: a deposited handle is a node fact of its home host (N3). It
@@ -45,8 +54,8 @@ ten model tools.
 - `a2a-net report <message…>` is a one-way report to the host's process team.
 - A message that starts with `-` goes after `--`. Flag values never become
   part of the message.
-- Output is one line (`delivered → <team> · task <id> · <receipt>`); `--json`
-  prints the raw reply.
+- Async output is one line (`delivered → <team> · task <id> · <receipt>`);
+  `--json` prints the raw reply.
 
 ## Receiving: the mailbox
 
@@ -71,8 +80,16 @@ ten model tools.
 ## Reading the host
 
 `whoami`, `teams [query]`, `status`, `tasks`, `probe` read the home host's
-state face (key-gated on a keyed host). `teams`, `tasks` and `probe` take
-`--json`.
+state face (key-gated on a keyed host). `--json` prints raw rows for
+`teams`, `tasks`, `probe`, `route`, `report`, `inbox` and `skills`.
+
+## Local commands
+
+- `a2a-net skills [name] [--root DIR] [--json]` lists the skills under the
+  local skill directory (default `~/.agents/skills`), or prints one by name.
+  It has no model-tool counterpart.
+- `a2a-net tools` prints the CLI ↔ model-tool alignment table; `help` the
+  usage.
 
 ## Exit codes
 

package/lib/skill/references/discovery.md

@@ -10,8 +10,11 @@ capability flags) plus unsigned serve-fresh fields.
 - The full card goes only to a caller that presents an OriginClaim envelope
   (`X-A2A-Caller` / `-Url` / `-Ts` / `-Sig`, signed with the caller's card
   key) AND that this host links: the same origin (self-fetch), one of its
-  joined session handles, or an exact canvas remote member ref the operator
-  added (#18, #19 D1). Proving a key is not a link.
+  joined session handles, an exact canvas remote member ref the operator
+  added (#18, #19 D1), or bilateral seeding — this host's `peers` config
+  names the caller's origin AND the caller's card lists this host's origin
+  among its peers (both operators made the gesture). Proving a key is not a
+  link.
 - Peers poll cards and aggregate the `sessionTeams` they are entitled to into
   their `remote` rows — this is how the planning canvas shows other nodes.
 

package/lib/skill/references/pitfalls.md

@@ -24,7 +24,8 @@
   the host that receives it; a team on another host answers "No live DSH
   session node accepts team". `a2a_route` resolves peers and forwards;
   direct callers (the CLI included) must target their home host's teams.
-- A sync route's 15s transport budget is shorter than most model turns. For
+- A sync route to a remote peer rides a 15s transport budget (a target on
+  this host gets 180s) — both are shorter than many model turns. For
   anything that runs long, prefer `async: true` and the receipt contract.
 
 ## Names and prefixes

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

@@ -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/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