From 196ee79eb06b2c21b2eb68fec1e81fe2b667482b Mon Sep 17 00:00:00 2001
From: yoshiyuki <yoshiyuki@yoshiyukis-MacBook-Pro-2.local>
Date: Thu, 4 Jun 2026 20:33:26 +0800
Subject: [PATCH 1/2] Reserve generation suffix for child keys

---
 .../src/handlers/agent/claim.rs               | 11 ++-
 .../src/handlers/agent/poll.rs                |  6 +-
 .../tests/agent_bootstrap_flow.rs             |  5 +-
 crates/agentkeys-core/src/actor_omni.rs       | 88 ++++++++++++++++++-
 docs/arch.md                                  | 28 +++---
 docs/wiki/blockchain-tee-architecture.md      |  2 +-
 6 files changed, 116 insertions(+), 24 deletions(-)

diff --git a/crates/agentkeys-broker-server/src/handlers/agent/claim.rs b/crates/agentkeys-broker-server/src/handlers/agent/claim.rs
index 5ccbe3a7..84b2ad3c 100644
--- a/crates/agentkeys-broker-server/src/handlers/agent/claim.rs
+++ b/crates/agentkeys-broker-server/src/handlers/agent/claim.rs
@@ -6,7 +6,8 @@
 //! named a master, so an unclaimed request is inert (Sybil-safe). On claim the
 //! broker:
 //!
-//! 1. derives the HDKD child omni `O_agent = SHA256(HDKD_DOMAIN || O_master || "//label")`
+//! 1. derives the HDKD child omni for the initial generation path
+//!    `//label/0`;
 //!    — the master "adopts" the agent under its own omni tree;
 //! 2. assigns `operator_omni` + `child_omni` + `label` + `requested_scope` onto
 //!    the (previously unbound) row, marking it claimed;
@@ -52,8 +53,12 @@ pub async fn pairing_claim(
 
     agentkeys_core::actor_omni::validate_label(&body.label)
         .map_err(|e| BrokerError::BadRequest(format!("invalid label: {e}")))?;
-    let child_omni = agentkeys_core::actor_omni::child_omni_hex(&master_omni, &body.label)
-        .map_err(|e| BrokerError::BadRequest(format!("derive child omni: {e}")))?;
+    let child_omni = agentkeys_core::actor_omni::child_omni_generation_hex(
+        &master_omni,
+        &body.label,
+        agentkeys_core::actor_omni::INITIAL_CHILD_GENERATION,
+    )
+    .map_err(|e| BrokerError::BadRequest(format!("derive child omni: {e}")))?;
 
     let requested_scope = body
         .requested_scope
diff --git a/crates/agentkeys-broker-server/src/handlers/agent/poll.rs b/crates/agentkeys-broker-server/src/handlers/agent/poll.rs
index 78c23b86..473faf44 100644
--- a/crates/agentkeys-broker-server/src/handlers/agent/poll.rs
+++ b/crates/agentkeys-broker-server/src/handlers/agent/poll.rs
@@ -96,7 +96,11 @@ pub async fn pairing_poll(
 
     // 3. Mint J1_agent fresh (HDKD omni + lineage). The agent authenticates with
     //    this immediately, but has NO scope until the master approves the binding.
-    let derivation_path = format!("//{label}");
+    let derivation_path = agentkeys_core::actor_omni::generation_derivation_path(
+        &label,
+        agentkeys_core::actor_omni::INITIAL_CHILD_GENERATION,
+    )
+    .map_err(|e| BrokerError::Internal(format!("derive J1_agent path: {e}")))?;
     let session_jwt = mint_agent_session_jwt(
         &state.session_keypair,
         &state.config.oidc_issuer,
diff --git a/crates/agentkeys-broker-server/tests/agent_bootstrap_flow.rs b/crates/agentkeys-broker-server/tests/agent_bootstrap_flow.rs
index 651209b3..2e471143 100644
--- a/crates/agentkeys-broker-server/tests/agent_bootstrap_flow.rs
+++ b/crates/agentkeys-broker-server/tests/agent_bootstrap_flow.rs
@@ -244,7 +244,7 @@ async fn full_request_claim_poll_pending_flow() {
     // Public recomputability (acceptance criterion).
     assert_eq!(
         child_omni,
-        agentkeys_core::actor_omni::child_omni_hex(&master_omni, "agent-a").unwrap()
+        agentkeys_core::actor_omni::child_omni_generation_hex(&master_omni, "agent-a", 0).unwrap()
     );
     assert_eq!(claim["operator_omni"], master_omni);
     assert_eq!(claim["request_id"], request_id);
@@ -277,8 +277,9 @@ async fn full_request_claim_poll_pending_flow() {
     );
     assert_eq!(
         claims.agentkeys.derivation_path.as_deref(),
-        Some("//agent-a")
+        Some("//agent-a/0")
     );
+    assert_eq!(claimed_poll["derivation_path"], "//agent-a/0");
     assert_eq!(
         claims.agentkeys.device_pubkey.as_deref(),
         Some(dk.address())
diff --git a/crates/agentkeys-core/src/actor_omni.rs b/crates/agentkeys-core/src/actor_omni.rs
index 8f83bcc3..6c2e7f8d 100644
--- a/crates/agentkeys-core/src/actor_omni.rs
+++ b/crates/agentkeys-core/src/actor_omni.rs
@@ -66,9 +66,13 @@ pub fn actor_omni_hex(wallet: &WalletAddress) -> String {
 /// Distinct from `DOMAIN` so a wallet-omni and a child-omni can never collide.
 const HDKD_DOMAIN: &[u8] = b"agentkeys-hdkd-v1";
 
-/// Validate an HDKD child label (`^[a-z0-9-]{1,32}$`). The label is spliced into
-/// the child-omni digest AND stored/echoed on chain + in JWT claims, so it must
-/// be a tight charset (no path separators, no whitespace, no uppercase).
+/// Initial child-key generation. The first pair flow always reserves the
+/// generation suffix by deriving at `<label>/0`.
+pub const INITIAL_CHILD_GENERATION: u32 = 0;
+
+/// Validate an HDKD child base label (`^[a-z0-9-]{1,32}$`). The label is stored
+/// and echoed as the logical agent name; derivation appends a numeric generation
+/// suffix separately, so the base label must stay path-separator-free.
 pub fn validate_label(label: &str) -> anyhow::Result<()> {
     if label.is_empty() || label.len() > 32 {
         return Err(anyhow::anyhow!(
@@ -85,6 +89,18 @@ pub fn validate_label(label: &str) -> anyhow::Result<()> {
     Ok(())
 }
 
+/// HDKD path segment for one logical agent generation, e.g. `agent-a/0`.
+pub fn generation_label(label: &str, generation: u32) -> anyhow::Result<String> {
+    validate_label(label)?;
+    Ok(format!("{label}/{generation}"))
+}
+
+/// JWT/audit derivation path for one logical agent generation, e.g.
+/// `//agent-a/0`.
+pub fn generation_derivation_path(label: &str, generation: u32) -> anyhow::Result<String> {
+    Ok(format!("//{}", generation_label(label, generation)?))
+}
+
 /// HDKD child actor omni (issue #144 / arch.md §6.2):
 ///
 /// ```text
@@ -108,6 +124,19 @@ pub fn child_omni(master_omni: &[u8; 32], label: &str) -> [u8; 32] {
     out
 }
 
+/// HDKD child actor omni for a logical agent at a numeric generation. This is
+/// the production path for pair/rotation flows; generation 0 is the initial
+/// child key, and higher generations intentionally produce different child
+/// omnis for key rotation without recycling the base label.
+pub fn child_omni_generation(
+    master_omni: &[u8; 32],
+    label: &str,
+    generation: u32,
+) -> anyhow::Result<[u8; 32]> {
+    let generation_label = generation_label(label, generation)?;
+    Ok(child_omni(master_omni, &generation_label))
+}
+
 /// [`child_omni`] over a hex parent omni (`0x`-prefixed or not), returning the
 /// child as **un-prefixed** 64-char lowercase hex — matching the `omni_account`
 /// JWT claim, the `agentkeys_actor_omni` PrincipalTag, and the `bots/<hex>/...`
@@ -127,6 +156,29 @@ pub fn child_omni_hex(master_omni_hex: &str, label: &str) -> anyhow::Result<Stri
     Ok(hex::encode(child_omni(&master, label)))
 }
 
+/// [`child_omni_generation`] over a hex parent omni, returning un-prefixed
+/// 64-char lowercase hex.
+pub fn child_omni_generation_hex(
+    master_omni_hex: &str,
+    label: &str,
+    generation: u32,
+) -> anyhow::Result<String> {
+    let h = master_omni_hex.trim();
+    let h = h.strip_prefix("0x").unwrap_or(h);
+    let bytes = hex::decode(h).map_err(|e| anyhow::anyhow!("parent omni not hex: {e}"))?;
+    if bytes.len() != 32 {
+        return Err(anyhow::anyhow!(
+            "parent omni must be 32 bytes, got {}",
+            bytes.len()
+        ));
+    }
+    let mut master = [0u8; 32];
+    master.copy_from_slice(&bytes);
+    Ok(hex::encode(child_omni_generation(
+        &master, label, generation,
+    )?))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -204,6 +256,29 @@ mod tests {
         );
     }
 
+    #[test]
+    fn child_omni_generation_appends_numeric_suffix() {
+        let parent = "00".repeat(32);
+        let gen0 = child_omni_generation_hex(&parent, "agent-a", 0).unwrap();
+        let explicit_path = child_omni_hex(&parent, "agent-a/0").unwrap();
+        assert_eq!(gen0, explicit_path);
+        assert_eq!(
+            generation_derivation_path("agent-a", INITIAL_CHILD_GENERATION).unwrap(),
+            "//agent-a/0"
+        );
+    }
+
+    #[test]
+    fn child_omni_generation_distinguishes_rotations() {
+        let parent = "11".repeat(32);
+        let gen0 = child_omni_generation_hex(&parent, "agent-a", 0).unwrap();
+        let gen1 = child_omni_generation_hex(&parent, "agent-a", 1).unwrap();
+        let gen2 = child_omni_generation_hex(&parent, "agent-a", 2).unwrap();
+        assert_ne!(gen0, gen1);
+        assert_ne!(gen1, gen2);
+        assert_ne!(gen0, gen2);
+    }
+
     #[test]
     fn child_omni_distinct_per_label_and_parent() {
         let p1 = "11".repeat(32);
@@ -233,4 +308,11 @@ mod tests {
         assert!(validate_label("agent a").is_err()); // whitespace
         assert!(validate_label(&"a".repeat(33)).is_err()); // too long
     }
+
+    #[test]
+    fn generation_helpers_reject_path_recycling_labels() {
+        assert!(generation_label("agent-a", 0).is_ok());
+        assert!(generation_label("agent-a/0", 0).is_err());
+        assert!(generation_label("agent a", 0).is_err());
+    }
 }
diff --git a/docs/arch.md b/docs/arch.md
index 434147ae..3be135ed 100644
--- a/docs/arch.md
+++ b/docs/arch.md
@@ -207,7 +207,7 @@ Pinned to disambiguate the same value showing up under different labels across c
 | `managed-wallet attestation` | **The stage-3 proof that the operator controls the derived managed wallet (K4).** The signer (TEE) produces an EIP-191 signature over the broker's challenge *on the wallet's behalf*; the broker verifies and mints the long-lived session JWT (J1); **`actor_omni` freezes here**. The operator never holds the wallet key — this is NOT a user-wallet sign-in. Distinct from the **K5 / `evm`-identity path** (§4 K5, §10.1), where the operator signs SIWE *directly* with their own MetaMask / hardware wallet (genuine Sign-In With Ethereum). | User-facing: **"activate your managed wallet"**. Small technical note: **SIWE / EIP-191, signer-performed** (the broker round-trip is SIWE-shaped). Aliases seen today: `SIWE → J1`, `SIWE round-trip`, `SIWE-bind`, "wallet attestation". |
 | `current_master_wallet` | **The current chain identity** = `HKDF(K3_v[current_epoch], O_master)`. Rotates each K3 epoch. Appears on chain as `msg.sender` in sovereign mode. The Layer 2 identifier per §6. | `master_wallet`, `wallet_address` (JWT claim shape pre-rotation), `MASTER_WALLET` (demo shell var). When historical K3 epochs are in scope, qualify with `master_wallet_K3_v[N]`. |
 | `identity_omni` | **The transient identity omni** — `SHA256("agentkeys" \|\| identity_type \|\| identity_value)`. Used internally by the broker between init and the managed-wallet attestation; never carried in a post-attestation JWT (J1). | `identity_omni_email` / `identity_omni_oauth2` (when narrowing to a specific identity type), `identity omni` (init-flow CLI log line). |
-| `agent_omni` | **A child actor omni** = `SHA256("agentkeys-hdkd-v1" \|\| O_master \|\| "//<label>")` (issue #144). **Public + recomputable** — anyone with the parent omni + label recomputes it; unforgeability is the master-gated `/v1/agent/pairing/claim` + the master-submitted on-chain binding, NOT a secret. (The "cannot be computed without the parent's master secret" property lives one layer down, at the K4 wallet `HKDF(K3_v[epoch], agent_omni)` in the signer.) Distinct from `master_omni`; both are valid actor_omnis. | `O_master//agent-A`, `O_agent_A` (HDKD-tree notation). |
+| `agent_omni` | **A child actor omni** = `SHA256("agentkeys-hdkd-v1" \|\| O_master \|\| "//<label>/<generation>")` (issue #144 + #8). Generation is a monotonic `u32` starting at `0`, so the initial pair flow derives at `//<label>/0`; rotation increments the suffix without recycling the base label. **Public + recomputable** — anyone with the parent omni + label + generation recomputes it; unforgeability is the master-gated `/v1/agent/pairing/claim` + the master-submitted on-chain binding, NOT a secret. (The "cannot be computed without the parent's master secret" property lives one layer down, at the K4 wallet `HKDF(K3_v[epoch], agent_omni)` in the signer.) Distinct from `master_omni`; both are valid actor_omnis. | `O_master//agent-A/0`, `O_agent_A_v0` (HDKD-tree notation). |
 | `K3` | The 32 bytes inside the signer enclave that K4 + KEK derivation HKDFs against. Per-epoch via `K3EpochCounter`. | `K3_v[N]` to disambiguate epoch; `master_secret` (signer-internal log term — discouraged). |
 | `session JWT` (= K6) | The bearer token at `~/.agentkeys/<id>/session.json` (or OS keychain). Signed by K1. Carries `agentkeys.actor_omni`, `agentkeys.device_pubkey`, `agentkeys.webauthn_cred_id` (master only). | `session_jwt`, `J1` (post-attestation bearer), `SESSION_JWT_A` / `SESSION_JWT_B` (demo shell vars). |
 | `OIDC JWT` (= K7) | Per-mint short-lived JWT signed by K2; consumed by `AssumeRoleWithWebIdentity`. Carries `agentkeys_actor_omni` claim → AWS session tag. | `oidc_jwt`, `JWT_A` / `JWT_B` (demo shell vars). |
@@ -270,31 +270,31 @@ flowchart LR
   ID_OMNI["identity omni<br/>= SHA256('agentkeys' || id_type || id_value)<br/>(transient — auth-event handle)"]
   M_OMNI["MASTER actor omni<br/>(root of HDKD tree)<br/>= SHA256('agentkeys' || 'evm' || initial_master_wallet)"]
   M_WALLET["current_master_wallet<br/>= HKDF(K3_v[epoch], O_master)"]
-  A_OMNI["AGENT actor omnis<br/>O_master//agent-A, //agent-B, ..."]
-  A_WALLET["wallet_agent_A<br/>= HKDF(K3_v[epoch], O_master//agent-A)"]
+  A_OMNI["AGENT actor omnis<br/>O_master//agent-A/0, //agent-B/0, ..."]
+  A_WALLET["wallet_agent_A<br/>= HKDF(K3_v[epoch], O_master//agent-A/0)"]
 
   ID -->|identity ceremony| ID_OMNI
   ID_OMNI -->|derive + link + attest + freeze| M_OMNI
   M_OMNI --> M_WALLET
-  M_OMNI -->|HDKD //label| A_OMNI
+  M_OMNI -->|HDKD //label/0| A_OMNI
   A_OMNI --> A_WALLET
 ```
 
 ```
 O_master                                wallet_master = HKDF(K3_v[epoch], O_master)
-├── O_master//agent-A                   wallet_agent_A = HKDF(K3_v[epoch], O_master//agent-A)
-├── O_master//agent-B                   wallet_agent_B = HKDF(K3_v[epoch], O_master//agent-B)
-│   └── O_master//agent-B//task-1       (sub-actors under agents)
+├── O_master//agent-A/0                 wallet_agent_A = HKDF(K3_v[epoch], O_master//agent-A/0)
+├── O_master//agent-B/0                 wallet_agent_B = HKDF(K3_v[epoch], O_master//agent-B/0)
+│   └── O_master//agent-B/0//task-1/0   (sub-actors under agents)
 └── ...
 ```
 
-The omni-tree edge `//<label>` is **public + recomputable** (issue #144): `O_child = SHA256("agentkeys-hdkd-v1" || O_parent || "//" || label)`. What "cannot be computed without the parent's master secret" is the per-node **wallet** (K4 = `HKDF(K3_v[epoch], O_node)`, derived in the signer) — not the omni node itself. Each node's wallet is a different EVM address; AWS PrincipalTag is per-actor `actor_omni` for prefix isolation. Only the master can *create* a binding for a child omni (the master-gated `/v1/agent/pairing/claim` + the master-submitted `registerAgentDevice`), so a public omni derivation never lets anyone bind a sibling.
+The omni-tree edge `//<label>/<generation>` is **public + recomputable** (issue #144 + #8): `O_child = SHA256("agentkeys-hdkd-v1" || O_parent || "//" || label || "/" || generation)`. Generation is a monotonic `u32` per logical base label; initial pairing uses generation `0`, and rotation uses `1`, `2`, ... so a rotated key gets a fresh omni/wallet without path recycling. What "cannot be computed without the parent's master secret" is the per-node **wallet** (K4 = `HKDF(K3_v[epoch], O_node)`, derived in the signer) — not the omni node itself. Each node's wallet is a different EVM address; AWS PrincipalTag is per-actor `actor_omni` for prefix isolation. Only the master can *create* a binding for a child omni (the master-gated `/v1/agent/pairing/claim` + the master-submitted `registerAgentDevice`), so a public omni derivation never lets anyone bind a sibling.
 
 **Why per-agent omni (not shared with master):**
 
 1. Per-agent compromise containment — leaked agent K10 touches only that agent's wallet/prefix.
 2. First-class audit attribution — audit rows carry `acting_actor_omni`, `parent_chain`, `derivation_path`.
-3. Atomic revocation — revoke `O_master//agent-A` alone; master and sibling agents untouched.
+3. Atomic revocation — revoke `O_master//agent-A/0` alone; master and sibling agents untouched.
 4. Tree topology IS the data model — no binding-table abstraction needed.
 
 ### 6.3 Identity ≠ actor ≠ machine ≠ capability
@@ -302,7 +302,7 @@ The omni-tree edge `//<label>` is **public + recomputable** (issue #144): `O_chi
 | Axis | What it answers | Realized by | Lifecycle |
 |---|---|---|---|
 | **Identity** | Who is the human? | identity omni (email / OAuth / EVM / passkey) | Recoverable via linked authenticators; identity omnis are ephemeral, masters are durable |
-| **Actor** | Master, or which agent? | actor_omni — a node in the HDKD tree | Master derived from identity at first init; agents derived from master via `//<label>` |
+| **Actor** | Master, or which agent? | actor_omni — a node in the HDKD tree | Master derived from identity at first init; agents derived from master via `//<label>/<generation>` |
 | **Machine** | Which physical box is signing right now? | K10 device pubkey (per-machine, per-actor); K11 WebAuthn (master only) | Per-box at init/rotation |
 | **Capability** | What is this actor allowed to do? | On-chain `ScopeContract[operator_omni][agent_omni] → {services, read_only}` + host-local sidecar policy (method/path/spend) | Master-issued via `set_scope_with_webauthn(...)`; chain-stored; revocable |
 
@@ -310,7 +310,7 @@ The omni-tree edge `//<label>` is **public + recomputable** (issue #144): `O_chi
 
 | | Master | Agent |
 |---|---|---|
-| HDKD position | Root | `//<label>` child of master |
+| HDKD position | Root | `//<label>/<generation>` child of master; initial pair uses `/0` |
 | K11 (WebAuthn) | Yes — needed for master mutations | No — agents have no human-presence credential |
 | Bootstrap | Identity ceremony + WebAuthn enrollment | **Link-code from master, only** |
 | Spawns other actors | Yes (claims agent pairing requests + grants scope) | No |
@@ -503,7 +503,7 @@ ON MASTER (already initialized; holds J1_master; master ≠ agent machine):
 8. Broker (J1_master bearer is the gate; K11 is NOT presented here — agents are
    K10-only per the contract, so there is nothing for the broker to K11-verify):
    - Verify J1_master; look up the UNBOUND request by pairing_code (atomic single-claim)
-   - Derive O_agent_A = SHA256(HDKD_DOMAIN || O_master || "//agent-A")
+   - Derive O_agent_A = SHA256(HDKD_DOMAIN || O_master || "//agent-A/0")
      [public + recomputable per §6.2 — the master "adopts" the agent under its omni
       tree; unforgeability is the J1_master claim + the master-submitted on-chain binding]
    - Bind the request to THIS operator_omni + O_agent_A + label + requested_scope;
@@ -518,7 +518,7 @@ ON AGENT MACHINE (continues polling from step 5):
       request's bound device key, then mints J1_agent FRESH (at retrieval — so no bearer
       secret sits at rest, and the JWT TTL starts when the agent actually fetches it):
       J1_agent { actor_omni=O_agent_A, parent_omni=O_master,
-                 derivation_path="//agent-A", device_pubkey=D_pub_agent }
+                 derivation_path="//agent-A/0", device_pubkey=D_pub_agent }
 11. Daemon: persist J1_agent; emit the binding artifact. The agent now authenticates
     but has NO scope yet (installed-but-not-yet-permitted).
 
@@ -1167,7 +1167,7 @@ for a worked example + the full PR checklist.
 - **K9 (DKIM) lives here**, sealed inside same TEE / KMS pattern as K3
 - **Send:** worker accepts cap-token + email payload; DKIM-signs; submits to SES; writes a copy to `sent/<yyyymm>/<message_id>`
 - **Receive:** SES routing Lambda (extension of existing #83 infrastructure) routes inbound mail to `inbound/<message_id>`; worker exposes `list-inbox(cap)` + `read-message(cap, msg_id)`
-- **Per-actor inbox:** `bots/<actor_omni_hex>/inbound/*` is keyed on actor; aliasing happens at the SES routing layer (e.g., `agent-a@bots.litentry.org` → `bots/<O_master//agent-A>/inbound/*`)
+- **Per-actor inbox:** `bots/<actor_omni_hex>/inbound/*` is keyed on actor; aliasing happens at the SES routing layer (e.g., `agent-a@bots.litentry.org` -> `bots/<O_master//agent-A/0>/inbound/*`)
 
 ### 15.5 payment-service
 
diff --git a/docs/wiki/blockchain-tee-architecture.md b/docs/wiki/blockchain-tee-architecture.md
index ac4e9635..45532527 100644
--- a/docs/wiki/blockchain-tee-architecture.md
+++ b/docs/wiki/blockchain-tee-architecture.md
@@ -610,6 +610,7 @@ Three rotation paths, each routine under HDKD + the new pallets (7b):
 
 - **OIDC-issuer key rotation** (`oidc/issuer/v1` → `v2`): new derivation path; both keys in JWKS during the grace window; `pallet-oidc-pubkeys` records both `kid`s as active; consumer JWKS cache refreshes naturally. No external party action required.
 - **Session-JWT key rotation** (`issuer/jwt/v1` → `v2`): same pattern, but the session-JWT key is internal (not on public JWKS). Clients re-authenticate gradually as old tokens expire; no coordinated flip.
+- **Child-agent key rotation** (`//agent-a/0` → `//agent-a/1`): the base label is stable for the same logical agent, while a monotonic `u32` generation suffix changes the derived actor key. Initial pairing always uses generation `0`; recycling the base label for a different agent remains disabled.
 - **MRSIGNER rotation** (new enclave-signing key): one attested seed handoff from the old enclave to the new one; `pallet-enclave-successors::authorize_mrsigner(new_mrsigner, ...)` extrinsic lands before the handoff; JWKS / custodial wallets / DKIM DNS are **unchanged** because the master seed survived. Relying parties who pinned on MRSIGNER do a one-time trust-policy update (automatable via the `agentkeys oidc-rotate-trust` CLI — see [`docs/spec/post-v0.1-future-work.md`](../spec/post-v0.1-future-work.md) §3.1).
 
 See [`docs/spec/heima-gaps-vs-desired-architecture.md`](../spec/heima-gaps-vs-desired-architecture.md) §8 and §9 for the pallet specifications and the MRSIGNER-rotation runbook.
@@ -647,4 +648,3 @@ Narrower surfaces with their own dedicated pages:
 - [#4](https://github.com/litentry/agentKeys/issues/4) — TEE-side per-session read rate limit
 - [#5](https://github.com/litentry/agentKeys/issues/5) — Pattern 4 audit submission (TEE-as-paymaster)
 - [#6](https://github.com/litentry/agentKeys/issues/6) — On-chain pair transport
-

From cfd5b3a2fdb8ff18cb3a649efc1e752b783bb140 Mon Sep 17 00:00:00 2001
From: yoshiyuki <yoshiyuki@yoshiyukis-MacBook-Pro-2.local>
Date: Thu, 4 Jun 2026 20:53:36 +0800
Subject: [PATCH 2/2] review: update daemon derivation_path validation for
 generation suffix

---
 .../src/handlers/agent/mod.rs                 |  2 +-
 .../agentkeys-broker-server/src/jwt/verify.rs |  2 +-
 crates/agentkeys-daemon/src/main.rs           | 29 ++++++++++++-------
 crates/agentkeys-daemon/src/ui_bridge.rs      |  8 ++---
 4 files changed, 25 insertions(+), 16 deletions(-)

diff --git a/crates/agentkeys-broker-server/src/handlers/agent/mod.rs b/crates/agentkeys-broker-server/src/handlers/agent/mod.rs
index d81491a5..4745625e 100644
--- a/crates/agentkeys-broker-server/src/handlers/agent/mod.rs
+++ b/crates/agentkeys-broker-server/src/handlers/agent/mod.rs
@@ -10,7 +10,7 @@
 //!   `pop_sig`, store an UNBOUND request (naming no master), return a
 //!   `pairing_code` to display + a secret `request_id` retrieval ticket.
 //! - `POST /v1/agent/pairing/claim` (master, `J1_master`-gated) — claim the
-//!   code; derive the HDKD child omni `O_agent = SHA256(.. || O_master || "//label")`,
+//!   code; derive the HDKD child omni `O_agent = SHA256(.. || O_master || "//label/0")`,
 //!   mark the request claimed, and stash the device artifact as a pending binding.
 //! - `POST /v1/agent/pairing/poll` (agent, no bearer) — once claimed, re-prove
 //!   device-key possession (fresh `pop_sig`) and mint + retrieve `J1_agent`.
diff --git a/crates/agentkeys-broker-server/src/jwt/verify.rs b/crates/agentkeys-broker-server/src/jwt/verify.rs
index 1f1e1586..620d431f 100644
--- a/crates/agentkeys-broker-server/src/jwt/verify.rs
+++ b/crates/agentkeys-broker-server/src/jwt/verify.rs
@@ -39,7 +39,7 @@ pub struct AgentKeysClaims {
     /// Agent only: the parent (master) omni this child was HDKD-derived from.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub parent_omni: Option<String>,
-    /// Agent only: the HDKD path, e.g. `"//agent-a"`.
+    /// Agent only: the HDKD path, e.g. `"//agent-a/0"`.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub derivation_path: Option<String>,
     /// Agent only: the K10 device address whose pop_sig redeemed the link code.
diff --git a/crates/agentkeys-daemon/src/main.rs b/crates/agentkeys-daemon/src/main.rs
index 8e57ee69..62c4e1d7 100644
--- a/crates/agentkeys-daemon/src/main.rs
+++ b/crates/agentkeys-daemon/src/main.rs
@@ -1483,12 +1483,17 @@ fn is_omni_hex(s: &str) -> bool {
 /// (`^[a-z0-9-]{1,32}$`), matching the broker's `format!("//{label}")`.
 fn is_derivation_path(s: &str) -> bool {
     match s.strip_prefix("//") {
-        Some(label) => {
+        Some(rest) => {
+            let Some((label, gen)) = rest.rsplit_once('/') else {
+                return false;
+            };
             !label.is_empty()
                 && label.len() <= 32
                 && label
                     .bytes()
                     .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
+                && !gen.is_empty()
+                && gen.bytes().all(|b| b.is_ascii_digit())
         }
         None => false,
     }
@@ -1911,7 +1916,7 @@ mod pairing_poll_tests {
             "0xdevice",
             "childomni",
             "operomni",
-            "//hermes",
+            "//hermes/0",
             "dkh",
             "popsig",
             "/s.jwt",
@@ -2178,8 +2183,8 @@ mod pairing_poll_tests {
         // Valid shapes (64-char lowercase hex omni; //label path) pass.
         assert!(is_omni_hex(&"0123456789abcdef".repeat(4)));
         assert!(is_omni_hex(&"a".repeat(64)));
-        assert!(is_derivation_path("//hermes"));
-        assert!(is_derivation_path("//agent-01"));
+        assert!(is_derivation_path("//hermes/0"));
+        assert!(is_derivation_path("//agent-01/0"));
 
         // Reflected tokens / wrong shapes are rejected — these would otherwise
         // be logged + printed on stdout from a claimed body.
@@ -2199,8 +2204,11 @@ mod pairing_poll_tests {
         for bad in [
             "//session_jwt=SENTINEL_JWT", // label charset
             "//UPPER",
-            "/hermes", // single slash
-            "//",      // empty label
+            "/hermes",  // single slash
+            "//",       // empty label
+            "//hermes", // missing generation suffix
+            "//hermes/",
+            "//hermes/a",
             "session_jwt=x",
             "",
         ] {
@@ -2216,12 +2224,13 @@ mod pairing_poll_tests {
         // 64-char lowercase hex operator omni; child is its REAL HDKD derivation
         // (the semantic check requires child_omni == HDKD(operator, label)).
         let operator = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
-        let child = agentkeys_core::actor_omni::child_omni_hex(operator, "hermes").unwrap();
+        let child =
+            agentkeys_core::actor_omni::child_omni_generation_hex(operator, "hermes", 0).unwrap();
         let ok = serde_json::json!({
             "session_jwt": "tok",
             "child_omni": child.clone(),
             "operator_omni": operator,
-            "derivation_path": "//hermes",
+            "derivation_path": "//hermes/0",
         });
         assert!(validate_claimed_binding(&ok).is_ok());
 
@@ -2242,7 +2251,7 @@ mod pairing_poll_tests {
         // Missing session_jwt is rejected (before any field/HDKD check) without
         // echoing the body.
         let no_jwt = serde_json::json!({
-            "child_omni": child.clone(), "operator_omni": operator, "derivation_path": "//hermes",
+            "child_omni": child.clone(), "operator_omni": operator, "derivation_path": "//hermes/0",
         });
         assert!(validate_claimed_binding(&no_jwt).is_err());
     }
@@ -2258,7 +2267,7 @@ mod pairing_poll_tests {
             "session_jwt": "tok",
             "child_omni": wrong_child,
             "operator_omni": operator,
-            "derivation_path": "//hermes",
+            "derivation_path": "//hermes/0",
         });
         let err = validate_claimed_binding(&v)
             .expect_err("HDKD child mismatch must be rejected")
diff --git a/crates/agentkeys-daemon/src/ui_bridge.rs b/crates/agentkeys-daemon/src/ui_bridge.rs
index 7210902c..08af3eea 100644
--- a/crates/agentkeys-daemon/src/ui_bridge.rs
+++ b/crates/agentkeys-daemon/src/ui_bridge.rs
@@ -1430,7 +1430,7 @@ mod tests {
             label: "FoloToy bear".into(),
             role: "agent".into(),
             parent: Some("master".into()),
-            derivation: "//folotoy".into(),
+            derivation: "//folotoy/0".into(),
             device: "FoloToy hardware".into(),
             device_pubkey: "D_pub_folotoy".into(),
             last_active: "now".into(),
@@ -1459,7 +1459,7 @@ mod tests {
             label: "FoloToy bear".into(),
             role: "agent".into(),
             parent: Some("master".into()),
-            derivation: "//folotoy".into(),
+            derivation: "//folotoy/0".into(),
             device: "FoloToy hardware".into(),
             device_pubkey: "D_pub_folotoy".into(),
             last_active: "now".into(),
@@ -1499,7 +1499,7 @@ mod tests {
                 omni_hex: "x".into(),
                 label: "agent-1".into(),
                 parent: Some("master".into()),
-                derivation: "//agent1".into(),
+                derivation: "//agent1/0".into(),
                 device: "".into(),
                 device_pubkey: "".into(),
                 last_active: "now".into(),
@@ -1713,7 +1713,7 @@ mod tests {
                     label: "seed".into(),
                     role: "agent".into(),
                     parent: Some("master".into()),
-                    derivation: "//seed".into(),
+                    derivation: "//seed/0".into(),
                     device: "".into(),
                     device_pubkey: "".into(),
                     last_active: "now".into(),